new-roadmap

<!-- GENERATED FROM .ai/ — do not edit directly. Run .ai/sync.sh to regenerate. -->

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

Create a detailed roadmap for $ARGUMENTS or the highest-priority topic needing a roadmap as per INDEX.md in the root directory. Favor $ARGUMENTS if provided.

Pre-conditions

• Only proceed if the selected topic currently lacks a detailed roadmap or user has explicitly requested a new roadmap.
• Check $ARGUMENTS for any user priority, specific instructions, or focus areas.
• The roadmap is complete when all subdirectories and files under the target directory have comprehensive documentation covering all necessary aspects of the topic.
• Do it step-by-step, level-by-level, ensuring each part is fully documented before moving to the next.

Process

Step 1: Research

Gather the latest information about the topic using available research tools. Focus on changelogs, migration guides, new features, and deprecations.

Step 2: Backward Design

Before writing content, design the assessments first:

1. Define what a learner should be able to DO after completing this roadmap (not just know).
2. Design the Self-Assessment questions and Challenge First problems for key topics.
3. Then work backward to determine what content, examples, and exercises are needed.

This ensures content serves the learning objectives, not the other way around.

Step 3: Concept Inventory (per topic)

Before writing any topic file, produce a concept inventory — a structured list of every concept, technique, pattern, and internal mechanism that belongs in the topic. This ensures comprehensive coverage from basics to Staff+ depth.

Depth Tiers

Organize concepts into these tiers:

Tier	What belongs here
Foundations	Definitions, mental models, "what is X", prerequisites
Core Mechanics	How it works, standard patterns, day-to-day usage
Advanced Patterns	Non-obvious techniques, tradeoffs, composition patterns, failure modes
Internals / Deep Dive	Under-the-hood mechanics, implementation details, why it works the way it does
Edge Cases & Pitfalls	What breaks, anti-patterns, common mistakes, subtle gotchas
Cross-cutting Concerns	Connections to other topics/domains, shared principles, opposing tradeoffs

Every tier must have at least one concept for Full topics. If a tier is genuinely empty, state why (e.g., "No meaningful internals — this is a pure design pattern").

Validation

Cross-check the inventory against:

1. Authoritative sources — Consult at least 3 sources (official docs, seminal books, conference talks, RFCs, established curricula). List the sources used.
2. Adjacent topic boundaries — Check what the previous and next topics in this level cover. Ensure no gaps between topics and no excessive overlap.
3. "What would a Staff+ engineer need?" test — For each tier, ask: "Would a Staff+ engineer consider this essential knowledge for deep understanding?" If yes and it's missing, add it.

Output Format

Produce the inventory before writing content:

Topic: [name]
Sources consulted: [list]

Foundations:
- [ ] Concept A
- [ ] Concept B

Core Mechanics:
- [ ] Concept C
- [ ] Concept D

Advanced Patterns:
- [ ] Concept E

Internals / Deep Dive:
- [ ] Concept F

Edge Cases & Pitfalls:
- [ ] Concept G

Cross-cutting Concerns:
- [ ] Concept H ↔ [other topic]

Every item must be checked off (covered in the final file) before the topic is considered complete.

Step 4: Create Structure

In the target directory, create a README.md that serves as the high-level roadmap:

• Outline the overall goal and audience.
• Break the roadmap into clear, ordered stages/steps (milestones or modules), each with a short description.

Follow the internal structure defined in .ai/templates/roadmap.md.

Step 5: Create Content

Iteratively, for each step in the roadmap, create or update a dedicated markdown doc (in the same directory or appropriate subdirectory).

Each topic file must follow .ai/templates/topic.md and adhere to .ai/guidelines/markdown.md. For natural-language roadmaps (English, Spanish, German, etc.) use .ai/templates/language-learning.md instead. For system design topics use .ai/templates/system-design.md.

After completing all content, create a blank memory sheet template at _progress/memory-sheets/[roadmap-name].md following .ai/templates/memory-sheet.md. This gives learners a retrieval exercise for after they complete the roadmap.

Step 6: Quality Gate (per topic)

Before moving to the next topic, verify against the topic's tier:

Full Topics — Section Depth Requirements

Section	Minimum Depth
Reference Material	Every major concept has ≥2 concrete examples (code, scenario, diagram, or comparison table)
Code Examples	≥3 distinct examples with explanations, covering basic → advanced usage
Real-World Production Cases	≥3 cases with tradeoff analysis or before/after comparison
Practice Exercises	≥3 exercises (graduated difficulty) + re-attempt of opening challenge
Challenge First	Requires genuine problem-solving, not just recall; has graduated hints
Self-Assessment	5 questions spanning Bloom's levels (recall → application → synthesis → evaluation)

Full Topics — Content Depth Signals

• Comparison tables or decision matrices for any concept with alternatives/tradeoffs
• At least one "what can go wrong" / failure mode analysis per major concept
• Cross-references to related topics in other levels or roadmaps where relevant
• Code examples include both "how to do it right" AND "common mistakes"

Soft-skill / Leadership Topics

Where code examples don't naturally apply, replace them with scenario analyses, conversation scripts, decision frameworks, or rubrics. Same depth requirements — different medium.

Lite Topics

≥1 code example, ≥1 exercise with solution. No further gate.

Concept Inventory Completion

Verify every item from the Step 3 Concept Inventory checklist is covered in the final file. Any unchecked item must be addressed or explicitly justified as out of scope.

Step 7: Structural Consistency

Any changes in the overall structure must be reflected in INDEX.md at the repo root.

Any changes in the internal structure of the roadmap must stay consistent with .ai/templates/roadmap.md.