Teach Me

# Stage 1: STUDY — The Learning Pipeline

The teacher must learn the material before teaching it. This stage has
a concrete, executable pipeline — not vague advice, but specific searches
to run, pages to fetch, and decisions to make.

## Step 0: Knowledge Assessment — What Do I Already Know?

The LLM already has training data. Some of it is reliable. Some isn't.
Before searching, assess what you already know and what you DON'T.

### What the LLM Typically KNOWS Well (use directly)

```
✅ RELIABLE from training data:
├── Definitions and core concepts (what is X)
├── Historical context (who invented it, when, why)
├── Mathematical foundations (formulas, theorems, proofs)
├── Conceptual explanations (how X works in principle)
├── Comparisons between established approaches (X vs Y)
├── Prerequisite relationships (what you need before X)
└── Stable fundamentals (Newton's laws, SQL syntax, Big O)
```

### What the LLM Typically DOESN'T Know (must search)

```
❌ UNRELIABLE — always search for these:
├── Current versions, APIs, syntax (things change)
├── Current best practices (evolve yearly)
├── Best TEACHING ORDER (pedagogical, not domain knowledge)
├── Common MISTAKES learners make (training data has answers, not wrong attempts)
├── Which RESOURCES are good (vs SEO-optimized junk)
├── Community consensus on tools (what's popular NOW)
├── Recent developments (papers, releases, breakthroughs)
└── Specific configuration recipes and setup steps
```

**Key insight**: The LLM knows WHAT things are. It doesn't reliably know
what's CURRENT, what's HARD, what MISTAKES people make, or what ORDER to teach.

---

## Step 1: Scope Assessment — How Big Is This Topic?

```
SMALL (1-3 concepts, single session):
  Examples: "async/await", "CSS flexbox", "binary search"
  Action: Light survey (2-3 searches) → teach immediately

MEDIUM (5-10 concepts, 3-5 sessions):
  Examples: "React hooks", "REST API design", "Playwright testing"
  Action: Full Phase 1 + Phase 2 → teach as multi-session

BIG (10+ concepts, multiple domains):
  Examples: "quantum physics", "machine learning", "full-stack development"
  Action: Full Phase 1 + Phase 2 → generate LEARNING ROADMAP
          Break into modules, teach one at a time
```

---

## Phase 1: SURVEY — Understand the Landscape

Broad research. Run these searches in order:

```
SEARCH 1: web_search "{topic} getting started guide"
  → Find the recommended entry point

SEARCH 2: web_search "{topic} key concepts beginners"
  → Identify core concepts list

SEARCH 3: web_search "site:ocw.mit.edu {topic}"
  → Find MIT's course structure (CS/math/science/engineering only)
  → Skip for specific tools/frameworks

SEARCH 4: web_search "{topic} common mistakes beginners"
  → Teaching gold — what goes wrong and why

SEARCH 5: web_search "{topic} vs {alternative}"
  → Comparison points for analogies (skip if no natural alternative)
```

### Fetch Top Results

```
From search results, web_fetch the 3-5 best pages:

PRIORITY 1: Official documentation or textbook page
PRIORITY 2: MIT OCW syllabus (if found)
PRIORITY 3: Best tutorial from Search 1
PRIORITY 4: Misconceptions article from Search 4

READ FULLY — don't rely on search snippets.
```

### Survey Output

```
After reading, compile:
├── Core concepts: [5-10 key ideas]
├── Prerequisites: [what learner needs before starting]
├── Subtopics: [how the topic breaks down into domains]
├── Best sources: [authoritative docs/courses found]
├── Teaching order hints: [how sources sequence topics]
├── Known difficulties: [what sources say is hard]
├── Common mistakes: [from Search 4]
└── Scope: [SMALL / MEDIUM / BIG]
```

---

## Phase 2: DEEP DIVE — Focused Research

Zoom into the specific concepts the learner needs.

### For Each Critical Concept

```
1. CHECK: Does the LLM already know this well?
   YES → note it, move on (don't waste searches)
   PARTLY → search to fill the specific gap
   NO → full research below

2. SEARCH: web_search "{concept} explained" or "{concept} tutorial"

3. FETCH: web_fetch the best result — READ IT FULLY

4. For practical topics:
   SEARCH: web_search "{concept} code example"
   FETCH: official docs for the specific API/feature

5. For academic topics:
   FETCH: MIT OCW lecture notes for relevant lectures
   FETCH: MIT OCW problem sets (for challenge design later)
```

### Deep Dive Output (per concept)

```
├── Explanation: [in own words — proves understanding]
├── Best example: [clearest demonstration found]
├── Why it's hard: [difficulty type]
├── Common mistake: [what goes wrong]
├── Analogy candidate: [familiar comparison]
└── Confidence: [HIGH / MEDIUM / LOW]

If LOW → search more. Don't proceed with gaps.
```

---

## Big Topic Handling — Learning Roadmap

When scope = BIG, generate a learning roadmap before teaching.

### What Is It?

A learning roadmap is a product roadmap for knowledge:

```
Product roadmap:          Learning roadmap:
├── Phase 1: MVP          ├── Module 1: Foundations
├── Phase 2: Features     ├── Module 2: Core Concepts
├── Phase 3: Scale        ├── Module 3: Applied Skills
└── Phase 4: Polish       └── Module 4: Advanced Topics
```

### Roadmap File Structure

Generate these files and present to the learner:

```
learning-roadmap-{topic}/
├── README.md                ← Overview + visual diagram + total time
├── module-1-foundations/
│   ├── overview.md          ← Objectives, prerequisites, time estimate
│   ├── concepts.md          ← Each concept explained briefly
│   ├── exercises.md         ← Practice problems / challenges
│   └── resources.md         ← OCW lectures, docs, videos, tools
├── module-2-core/
│   ├── overview.md
│   ├── concepts.md
│   ├── exercises.md
│   └── resources.md
├── module-3-applied/
│   └── ...
└── module-4-advanced/
    └── ...
```

### README.md Must Include

```markdown
# Learning Roadmap: [Topic]

## Who Is This For
[Target audience and prerequisites]

## Visual Roadmap

Module 1          Module 2          Module 3          Module 4
Foundations   →   Core          →   Applied       →   Advanced
~3 hours          ~5 hours          ~4 hours          ~6 hours
[concept list]    [concept list]    [concept list]    [concept list]

(Show dependencies: which modules require which)

## How to Use
1. Start with Module 1
2. Complete exercises before advancing
3. Use /teach-me [module topic] for interactive sessions
4. Modules with no dependency can be done in any order

## Total Time: ~X hours
```

### Example: Quantum Physics Roadmap

```
Module 1: Why Quantum? (3 hours)
├── Classical physics and its limits
├── Photoelectric effect, Compton scattering
├── Wave-particle duality
├── de Broglie wavelength
└── Milestone: Explain why classical physics fails for atoms

Module 2: The Quantum Framework (5 hours)
├── Wavefunctions and probability
├── Superposition (not "in two places at once"!)
├── Measurement and decoherence
├── Uncertainty principle
├── Schrödinger equation (intro)
└── Milestone: Predict double-slit experiment outcomes

Module 3: Solving Quantum Problems (4 hours)
├── Particle in a box
├── Quantum tunneling
├── Harmonic oscillator
├── Energy quantization
└── Milestone: Solve a 1D quantum well problem

Module 4: Real Atoms (6 hours)
├── 3D quantum mechanics
├── Angular momentum and spin
├── Hydrogen atom
├── Periodic table from quantum principles
└── Milestone: Explain hydrogen's emission spectrum

Source: MIT 8.04 (Zwiebach, Spring 2016)
```

### How Teaching Works with a Roadmap

```
1. Generate roadmap → present to learner
2. Ask: "Which module would you like to start with?"
3. For chosen module:
   - Run Stages 2-5 on THAT MODULE only
   - Teach interactively (Stage 6)
   - When done, offer next module
4. Learner can:
   - Go sequentially (recommended)
   - Jump to a specific module (if they have prereqs)
   - Ask for a course version: /teach-me [module] --course
```

---

## Combined Example

```
User: /teach-me quantum physics

STEP 0 — KNOWLEDGE ASSESSMENT:
  LLM knows: what QM is, history, core math, key concepts
  LLM needs: teaching order, common mistakes, current resources

STEP 1 — SCOPE: BIG → will generate roadmap

PHASE 1 — SURVEY:
  web_search: "quantum physics getting started guide"
  web_search: "site:ocw.mit.edu quantum physics"  → MIT 8.04
  web_search: "quantum physics common misconceptions"
  web_fetch: MIT 8.04 syllabus → topic order extracted
  web_fetch: misconceptions article → 4 major ones found

PHASE 2 — DEEP DIVE (per critical concept):
  Superposition: LLM knows concept, searched for learner mistakes → HIGH
  Measurement: LLM knows concept, searched for teaching approach → HIGH
  Schrödinger eq: LLM knows math, fetched MIT lecture notes → HIGH

ROADMAP GENERATED:
  Created learning-roadmap-quantum-physics/ with 4 modules
  Presented to learner with visual diagram

FIRST MESSAGE:
  "I've built a learning roadmap for quantum physics based on
   MIT's curriculum. It's 4 modules, about 18 hours total.
   [presents roadmap file]
   Which module would you like to start with? If you're brand
   new, Module 1 is the place — we'll start with why classical
   physics breaks down, which is genuinely one of the most
   fascinating stories in science."
```

---

## Study Completion Check

```
□ Knowledge assessment done (know vs. don't know mapped)
□ Scope determined (small / medium / big)
□ Phase 1 Survey complete (5 searches, 3-5 pages fetched and read)
□ Phase 2 Deep Dive complete (critical concepts at HIGH confidence)
□ If BIG: roadmap generated with modules, times, and milestones
□ Ready to proceed to Stage 2 (Understand)
```