Roadmap

---
name: roadmap
description: "Use when the student wants a visual learning roadmap for a goal or topic area — reads current knowledge state, researches the standard learning path, and generates an interactive .excalidraw diagram with color-coded topic nodes, prerequisite arrows, and milestone markers. Visual companion to /claude-teacher:research."
argument-hint: "[goal or topic area]"
---

Requested topic/task: $ARGUMENTS

Before accessing education data, read `${CLAUDE_PLUGIN_ROOT}/references/education-data.md`. Resolve every `<education-db>` below using that contract. Current session ID: `${CLAUDE_SESSION_ID}`.

# Roadmap — Visual Learning Path Generator

Generates an interactive `.excalidraw` diagram showing the full learning path for a goal or topic area, with nodes color-coded by the student's current knowledge state. Also saves a markdown companion with the same information as text.

## Invocation

`/claude-teacher:roadmap <goal or topic area>`

Examples:
- `/claude-teacher:roadmap backend development`
- `/claude-teacher:roadmap networking fundamentals`
- `/claude-teacher:roadmap prepare for AWS exam`
- `/claude-teacher:roadmap learn Rust from scratch`

## Process

### 1. Understand Current State

1. Read `<education-db>/student.json` — get goals, level, known technologies, learning style, interests
2. Read `<education-db>/dashboard.json` — get all tracked topics and statuses
3. For topics relevant to the goal, read individual `<education-db>/topics/<slug>.json` files — get depth, prerequisites, misconceptions
4. If the student has no profile yet, say: "Run `/claude-teacher:init-edu` first so I can personalize your roadmap."

### 2. Research the Learning Path

Use **WebSearch** to research the standard, industry-accepted learning path for the given goal:

- Search for curricula, official certification paths, university course sequences, and community-recommended learning orders
- Identify 8-20 topics that form the path (scale to goal size)
- Determine prerequisite relationships between topics (which must come before which)
- Identify 2-4 milestones — meaningful checkpoints where the student can build something or demonstrate competence
- Note which topics the student already knows (cross-reference with dashboard)

**Rules:**
- Every topic in the roadmap must be verified as genuinely part of the learning path — no filler
- Prerequisites must reflect real dependencies (e.g., you truly need TCP basics before HTTP internals)
- Milestones should be concrete achievements, not vague labels ("Can build a REST API" not "Understands backend")

### 3. Classify Each Topic

For every topic in the roadmap, assign a status based on the student's current knowledge:

| Status | Color | Meaning |
|--------|-------|---------|
| `solid` | Green (`#BFDBAD`) | Student has proven understanding — no work needed |
| `learned` | Blue (`#BDD0E8`) | Student knows it but needs more practice or review |
| `weak` | Red (`#F5C4C4`) | Student has seen it but struggles — needs reteaching |
| `new` | Gray (`#E8E8E8`) | Not yet covered — upcoming |

Also mark:
- **Current position** — the frontier between known and unknown topics, highlighted with a bold border or star marker
- **Milestones** — diamond shapes or double-bordered rectangles at key achievement points

### 4. Generate the Excalidraw Diagram

Invoke `/claude-teacher:excalidraw` internally to generate the `.excalidraw` file. The diagram must follow these structural rules:

#### Layout

- **Top-to-bottom flow** — earliest prerequisites at top, advanced topics at bottom
- **Parallel tracks side by side** — topics that can be learned independently sit in parallel columns
- **Milestones span the full width** — horizontal milestone bars separate phases
- Grid-aligned coordinates (multiples of 20), max ~1400px wide, ~1000px tall per section

#### Node Design

Each topic is a rounded rectangle containing:
- Topic name (fontSize 20, bold)
- Status indicator text (fontSize 14): "solid", "learned", "weak", or "new"
- Background color matching status (see table above)

#### Arrows

- Solid arrows from prerequisite to dependent topic
- Arrow labels are optional — use only when the dependency reason is non-obvious
- Prefer straight vertical/horizontal arrows; use waypoints for complex routing

#### Current Position

- The topic(s) the student should work on next get a thicker border (strokeWidth 3) and a subtle glow effect (use a slightly larger shadow rectangle behind the node)
- Add a free-floating label: "YOU ARE HERE" (fontSize 16, bold) with an arrow pointing to the current position

#### Milestones

- Diamond shapes or wide rectangles with dashed borders
- Label format: "MILESTONE: [achievement]" (fontSize 18)
- Examples: "MILESTONE: Can build a basic HTTP server", "MILESTONE: Ready for networking exam"

#### Title and Legend

- Title at top: "[Goal] — Learning Roadmap" (fontSize 28)
- Legend in top-right corner showing color meanings:
  - Green = Solid (mastered)
  - Blue = Learned (needs practice)
  - Red = Weak (needs reteaching)
  - Gray = New (upcoming)
- Source attribution at bottom (fontSize 12)

### 5. Generate the Markdown Companion

Create a text version of the same roadmap:

```markdown
# Learning Roadmap: [Goal]

> Generated: [date]
> Student level: [from student.json]
> Topics: N total (X solid, Y learned, Z weak, W new)

---

## Phase 1: Foundations
*Prerequisites that everything else builds on*

- [x] **Topic A** (solid) — [one-line description]
- [ ] **Topic B** (new) — [one-line description]
  - Prerequisites: Topic A
  - Why: [why this matters for the goal]

> MILESTONE: [what you can do after this phase]

---

## Phase 2: Core Skills
*The main knowledge area for your goal*

- [ ] **Topic C** (learned) — [one-line description]
  - Prerequisites: Topic A, Topic B
  - Why: [relevance]
- [ ] **Topic D** (new) — [one-line description]
  - Prerequisites: Topic C

  --> YOU ARE HERE <--

> MILESTONE: [achievement after this phase]

---

## Phase 3: Advanced / Specialization

- [ ] **Topic E** (new) — [description]
- [ ] **Topic F** (new) — [description]

> MILESTONE: [final achievement — goal reached]

---

## Suggested Path

1. Topic A -> Topic B (sequential — B needs A)
2. Topic C + Topic D (parallel — independent of each other)
3. Topic E -> Topic F (sequential)

## Sources

- [Source 1](url) — used to determine topic sequence
- [Source 2](url) — prerequisite relationships
```

**Checklist symbols:**
- `[x]` = solid (done)
- `[ ]` with a status label = learned or weak (in progress)
- `[ ]` = new (not started)

### 6. Save Files

Save to **four locations**:

1. **Project-local diagram:** `docs/roadmap-<goal-slug>.excalidraw`
2. **Project-local markdown:** `docs/roadmap-<goal-slug>.md`
3. **Global diagram:** `<education-db>/docs/roadmap-<goal-slug>.excalidraw`
4. **Global markdown:** `<education-db>/docs/roadmap-<goal-slug>.md`

Tell the student the file paths and how to open the `.excalidraw` file (VS Code extension or excalidraw.com).

### 7. Update the Education DB

**For each NEW topic in the roadmap not already in the DB:**
- Create `<education-db>/topics/<slug>.json` with:
  - `status: "new"`
  - `depth: "surface"`
  - `first_seen`, `last_reviewed`, `next_review`: `null` (planned, untaught)
  - `review_interval_days: 1`
  - `prerequisites` filled from the roadmap structure
  - `related_topics` filled from adjacent nodes
- Update `dashboard.json` to include the new topics

**Append to session log** `<education-db>/sessions/[date].jsonl`:
```jsonl
{"time": "[now]", "event": "roadmap", "goal": "[goal description]", "diagram_file": "docs/roadmap-<goal-slug>.excalidraw", "markdown_file": "docs/roadmap-<goal-slug>.md", "topics_total": N, "topics_known": X, "topics_new": Y, "milestones": ["milestone1", "milestone2"]}
```

## Adaptation Rules

**Based on student level (from student.json):**
- **Beginner**: More granular topics (break big topics into smaller steps), more milestones for encouragement, 12-20 nodes
- **Intermediate**: Standard granularity, skip basics that are clearly beneath their level, 8-15 nodes
- **Advanced**: Coarser topics, focus on specialization branches, include cutting-edge/advanced subtopics, 8-12 nodes

**Based on learning style:**
- **Visual learner**: Emphasize the diagram — make it detailed and well-structured
- **Hands-on learner**: Add "Build:" annotations to milestone nodes (what to build at each checkpoint)
- **Reader**: Make the markdown companion more detailed with resource links per topic

**Based on time commitment:**
- If tight deadline: highlight the critical path (shortest route to the goal), mark optional branches clearly
- If open-ended: show the full breadth including nice-to-have branches

## Quality Rules

- Every topic must genuinely belong in the learning path (verified via WebSearch)
- Prerequisite arrows must reflect real dependencies, not arbitrary ordering
- Color coding must accurately reflect the student's current state from the DB
- "YOU ARE HERE" must point to the correct frontier — the first new/weak topic(s) whose prerequisites are all solid/learned
- Milestones must be concrete and achievable ("Can build X" or "Can explain Y to others")
- The diagram must pass the Excalidraw quality checklist (isomorphism test, education test, container ratio, binding consistency)
- The markdown companion must contain all the same information as the diagram in accessible text form

## Integration with Other Skills

- **`/claude-teacher:excalidraw`** — roadmap uses `/claude-teacher:excalidraw` to generate the diagram. Follow all excalidraw reference files and quality rules.
- **`/claude-teacher:research`** — text-based study plan companion. `/claude-teacher:roadmap` is the visual overview, `/claude-teacher:research` provides detailed resources per topic. Suggest: "Want detailed resources for any of these topics? Run `/claude-teacher:research [topic]`."
- **`/claude-teacher:progress`** — after generating a roadmap, suggest `/claude-teacher:progress` to see the detailed dashboard. As the student progresses, re-running `/claude-teacher:roadmap` shows updated colors.
- **`/claude-teacher:quiz-me`** — suggest quizzing on learned/weak topics shown in the roadmap to promote them to solid.
- **`/claude-teacher:challenge`** — suggest challenges at milestone points to verify readiness before moving on.
- **`/claude-teacher:summary`** — session summary can reference roadmap progress.
- Re-running `/claude-teacher:roadmap` with the same goal produces an **updated** diagram reflecting new knowledge state — encourage the student to re-run periodically to see visual progress.