Teach Me

# Roadmap Builder — Handling Large Topics

When a topic is too big for a single session (like quantum physics, machine learning,
or full-stack development), generate a **learning roadmap** — a structured path
the learner can follow across multiple sessions.

## When to Generate a Roadmap

```
TRIGGER: Phase 1 Survey reveals the topic is LARGE:
  - More than 10 core concepts identified
  - MIT OCW course is 10+ lectures
  - Official docs have 20+ pages
  - The learner would need 3+ hours to cover everything
  - Topic has clear sub-domains (e.g., "ML" = supervised + unsupervised + deep + RL)

ACTION: Generate a roadmap BEFORE teaching. Tell the learner:
  "This is a big topic — let me build you a learning roadmap first,
   then we'll tackle it module by module."
```

## Roadmap Structure

A roadmap breaks a large topic into **modules**, each module into **sessions**:

```
ROADMAP: [Topic Name]
│
├── Module 1: [Foundation]  ← START HERE
│   ├── Session 1.1: [concept] (20 min)
│   ├── Session 1.2: [concept] (25 min)
│   └── Session 1.3: [concept] (30 min)
│   └── ✅ Milestone: [what you can do after this module]
│
├── Module 2: [Core Skills]  ← requires Module 1
│   ├── Session 2.1: [concept] (25 min)
│   ├── Session 2.2: [concept] (30 min)
│   └── Session 2.3: [concept] (35 min)
│   └── ✅ Milestone: [what you can do now]
│
├── Module 3: [Applied]  ← requires Module 1 + 2
│   └── ...
│
└── Module 4: [Advanced]  ← requires all above
    └── ...
```

## How to Build a Roadmap

### Step 1: Identify Modules

From your Phase 1 Survey, group concepts into natural modules:

```
Look for NATURAL BOUNDARIES:
├── Prerequisite clusters (concepts that share prerequisites)
├── Difficulty tiers (beginner → intermediate → advanced)
├── Topic sub-domains (for "ML": supervised / unsupervised / deep / RL)
├── MIT OCW "Parts" (they often split courses into numbered parts)
└── Official docs sections (getting started / guides / advanced / reference)

SIZING: Each module should be:
├── 2-5 sessions
├── 1-3 hours total
├── Completable in one sitting (or two)
└── End with a meaningful milestone
```

### Step 2: Order Modules

```
Module ordering rules:
1. Foundation module ALWAYS first (prerequisites, setup, "why")
2. Core skills before applied skills
3. Each module only depends on PREVIOUS modules (no forward references)
4. A learner can STOP after any module and still have useful knowledge
5. The most "unlocking" module comes earliest (teaches the most reusable skills)
```

### Step 3: Define Milestones

Each module needs a milestone — what can the learner DO after completing it?

```
GOOD MILESTONES:
✅ Module 1: "You can explain the photoelectric effect and predict
   whether a given photon will eject an electron from a metal"
✅ Module 2: "You can set up and solve Schrödinger's equation for
   a particle in a 1D box and calculate energy levels"
✅ Module 3: "You can calculate hydrogen atom energy levels and
   explain why the periodic table has the structure it does"

BAD MILESTONES:
❌ "You understand quantum mechanics" (too vague)
❌ "You've covered the material" (not a skill)
```

## Roadmap Output Formats

### Interactive Display (for /teach-me sessions)

Show the roadmap visually before teaching. Use a diagram or structured list
that the learner can see their position in:

```
📍 YOU ARE HERE
│
├── ✅ Module 1: Why Classical Physics Breaks (complete)
│   ├── ✅ 1.1 Photoelectric effect
│   ├── ✅ 1.2 Wave-particle duality
│   └── ✅ 1.3 Superposition & measurement
│
├── 🔵 Module 2: The Math of Quantum (current)
│   ├── 🔵 2.1 Wavefunctions ← you are here
│   ├── ⬜ 2.2 Schrödinger equation
│   └── ⬜ 2.3 Uncertainty principle
│
├── ⬜ Module 3: Solving Real Problems
│   ├── ⬜ 3.1 Particle in a box
│   ├── ⬜ 3.2 Tunneling
│   └── ⬜ 3.3 Harmonic oscillator
│
└── ⬜ Module 4: Atoms & Beyond
    ├── ⬜ 4.1 Angular momentum
    ├── ⬜ 4.2 Hydrogen atom
    └── ⬜ 4.3 Where to go next
```

### Stored Roadmap (for files)

When generating a course or when the learner wants to save their progress,
store the roadmap as files:

```
learning-roadmap/
├── ROADMAP.md                ← Overview with module descriptions + diagram
├── progress.json             ← Track which sessions are complete
├── module-1-foundation/
│   ├── README.md             ← Module overview, prerequisites, milestone
│   ├── session-1-1.md        ← Full session content or teaching notes
│   ├── session-1-2.md
│   └── session-1-3.md
├── module-2-core/
│   ├── README.md
│   └── ...
└── resources/
    ├── concept-map.md        ← Visual concept dependency map
    ├── misconceptions.md     ← Collected misconceptions with corrections
    └── further-reading.md    ← Curated resource list
```

### ROADMAP.md Template

```markdown
# Learning Roadmap: [Topic]

## Overview
[2-3 sentences: what you'll learn and where you'll end up]

## Prerequisites
[What the learner should already know before starting]

## Estimated Total Time
[X hours across Y modules]

## The Path

### Module 1: [Name] (X hours)
[1-2 sentence description]
- Session 1.1: [Title] — [concept] (XX min)
- Session 1.2: [Title] — [concept] (XX min)  
- Session 1.3: [Title] — [concept] (XX min)
- **Milestone**: [what you can do after this]

### Module 2: [Name] (X hours)
*Requires: Module 1*
[description]
- Session 2.1: ...
...

## Concept Map
[Mermaid diagram or text-based dependency graph]

## How to Use This Roadmap
1. Work through modules in order (each builds on the previous)
2. Complete all sessions in a module before moving to the next
3. At each milestone, verify you can do what it says
4. If stuck, revisit the previous module's sessions
5. You can stop after any module — each is self-contained at its level
```

## Example: Quantum Physics Roadmap

```
ROADMAP: Quantum Physics
Total: ~8-12 hours across 4 modules

Module 1: Why Quantum? (2 hours)
  Prereqs: High school physics, basic algebra
  1.1 Classical Physics Breaks (20 min) — photoelectric effect, blackbody
  1.2 Light is Both (25 min) — wave-particle duality, double slit
  1.3 Probability Rules (25 min) — superposition, measurement, uncertainty
  1.4 The Quantum World (20 min) — entanglement, what QM actually says
  Milestone: Explain why quantum physics exists and what makes it different
  Track: conceptual (no calculus needed)

Module 2: The Language of Quantum (2.5 hours)
  Prereqs: Module 1 + calculus basics (derivatives, integrals)
  2.1 Wavefunctions (30 min) — what ψ is, probability density |ψ|²
  2.2 Schrödinger Equation (35 min) — time-dependent, time-independent
  2.3 Operators and Observables (25 min) — measurement in math
  2.4 Uncertainty in Math (25 min) — commutators, Heisenberg formalism
  Milestone: Set up and interpret the Schrödinger equation
  Track: mathematical

Module 3: Solving Quantum Problems (3 hours)
  Prereqs: Module 2
  3.1 Particle in a Box (30 min) — quantized energy, standing waves
  3.2 Potential Barriers (35 min) — tunneling, transmission coefficients
  3.3 Harmonic Oscillator (40 min) — creation/annihilation operators
  3.4 Two-State Systems (25 min) — spin, qubits
  Milestone: Solve the Schrödinger equation for standard potentials

Module 4: Atoms and Beyond (2.5 hours)
  Prereqs: Module 3
  4.1 3D Quantum Mechanics (30 min) — spherical coordinates, angular momentum
  4.2 Hydrogen Atom (35 min) — energy levels, orbitals, spectrum
  4.3 What's Next (20 min) — QFT, quantum computing, open questions
  Milestone: Calculate hydrogen atom properties, know where to go deeper
```

## Roadmap for Non-STEM Topics

The same structure works for any large topic:

```
Machine Learning → Modules: Math foundations → Supervised → Unsupervised → Deep → RL
Web Development → Modules: HTML/CSS → JavaScript → Framework → Backend → Deployment
Music Theory → Modules: Notes & scales → Chords → Rhythm → Harmony → Composition
Economics → Modules: Micro → Macro → Econometrics → Policy → Behavioral
History → Modules: by era or by theme, each with key events + analysis
```

## When the Learner Returns

If a learner comes back for a second session on a roadmapped topic:

```
1. Check where they left off (ask: "Last time we covered [X]. Ready for [Y]?")
2. Quick review of previous module's milestone (can they still do it?)
3. If yes → proceed to next module
4. If no → brief recap of key concepts, then proceed
5. Show the roadmap with their progress updated
```