new-walkthrough

Prompt file imported from MohammadBafkar/whetstone (.windsurf/workflows/new-walkthrough.md). Fill in {{arguments}} before use. Copyright stays with the author.

Create a comprehensive, production-ready walkthrough for a topic with hands-on exercises

Mode: Content Creation — provide complete, production-ready examples. Do NOT use hint escalation.

Create a comprehensive, production-ready walkthrough for {{arguments}} that guides users from initial setup to real-world, battle-tested implementations. The walkthrough should be hands-on, practical, and reflect how the technology is actually used in production environments.

Pre-conditions

• Only proceed if a roadmap already exists for the target topic; otherwise, suggest using new-roadmap first.
• Check {{arguments}} for any user-specified focus areas, use cases, or specific scenarios to prioritize.
• The output should be placed in a walkthroughs/ subdirectory within the target roadmap directory.
• Each walkthrough file should be extensive with complete, runnable code examples.
• All code examples must be production-ready with proper error handling, logging, and security considerations.
• For programming language roadmaps, include at least one end-to-end applied build, not just concept notes.
• Prefer a problem-first format with drills and exercises. Non-trivial solutions should be hidden behind collapsible <details> blocks, and add a short explanation whenever the reasoning is not obvious from the code alone.

Process

Step 1: Gather Latest Information

Gather the latest information using available research tools. Focus on:

• Release notes and changelogs
• Installation guides and getting started docs
• New features and APIs
• Deprecation notices
• Security advisories and hardening guides
• Production deployment and scaling best practices

Additional research (always perform):

• Search for "[tool] production best practices [current year]"
• Search for "[tool] security hardening [current year]"
• Check major cloud providers' documentation for managed service updates
• Review CNCF/Linux Foundation announcements if applicable

Step 2: Identify Production Use Cases

Research and compile:

1. Common Production Scenarios - How the technology is typically used in real-world applications.
2. Industry Patterns - Patterns used by major companies (FAANG, startups, enterprises).
3. Integration Points - How it integrates with other tools in the ecosystem.
4. Scaling Considerations - How to scale from development to production.
5. Security Requirements - Production security configurations and hardening.
6. Observability Needs - Monitoring, logging, and tracing in production.

Step 3: Design Challenge-First and Retrieval Checkpoints

Before writing the walkthrough content:

1. Challenge First: Design an opening challenge for the walkthrough that is partially solvable with adjacent knowledge. Place this before the Overview section.
2. Retrieval Checkpoints: Plan 2-3 retrieval checkpoints at major milestones throughout the walkthrough. After each major section, include:
   • Close the walkthrough prompt
   • 3 recall questions (what, why, what-if)
   • Reopen and check instruction
3. Predict-Code-Reflect: For key implementation steps, use the predict-code-reflect pattern: present the problem, let the learner try, then show the solution with explanation.

Follow the patterns defined in .ai/templates/walkthrough.md.

Step 4: Create Walkthrough Structure

Follow the directory structure and templates defined in .ai/templates/walkthrough.md.

Step 5: Write Content

Create each file following the individual walkthrough file template from .ai/templates/walkthrough.md. Ensure all code examples meet the quality standards defined there.

Step 6: Structural Consistency

• Link the walkthrough directory from the main README.md of the roadmap.
• Update .ai/templates/roadmap.md structure if needed.
• Update INDEX.md if new categories are added.