Teach Me

# Learning Pipeline — Concrete Execution Plan

This is the ACTIONABLE version of Stages 1-2. Instead of philosophy,
this file tells you exactly WHAT to search, WHAT to fetch, and WHAT to extract.

## When to Use This Pipeline

```
ALWAYS run this pipeline before teaching. The depth depends on the topic:

SMALL TOPIC (one concept — "async/await", "CSS grid"):
  → Phase 1 only (5 min), skip Phase 2

MEDIUM TOPIC (a tool or framework — "Playwright", "React hooks"):
  → Phase 1 (10 min) + Phase 2 on the specific area (15 min)

LARGE TOPIC (an entire field — "quantum physics", "machine learning"):
  → Phase 1 (15 min) + Phase 2 (30 min) + generate a ROADMAP
  → Read references/roadmap-builder.md for roadmap generation
```

## Does the LLM Already Know This?

```
QUICK DECISION:

The LLM's training data is RELIABLE for:
✅ Math theorems and proofs (these don't change)
✅ Physics laws and equations (F=ma hasn't changed)
✅ Algorithm logic (how quicksort works)
✅ Language fundamentals (what a Python dict is)
✅ Design pattern concepts (what observer pattern does)
✅ Historical facts about the topic

The LLM's training data is UNRELIABLE for:
❌ Current API signatures (methods get renamed)
❌ Current best practices (these evolve yearly)
❌ Version-specific details (flags, config options)
❌ Which tools/libraries are currently recommended
❌ Current state of research fields
❌ Anything the learner might copy-paste and run

RULE: Even for topics the LLM "knows," ALWAYS search for:
  1. Common misconceptions (you need real ones, not guessed ones)
  2. Best teaching order (what MIT/experts use, not your default)
  3. Current state (has anything changed recently?)
```

---

## Phase 1: SURVEY — Understand the Landscape (5-15 min)

Goal: Build a bird's-eye view of the topic. After this phase, you should know
what the major concepts are, what order to learn them, and where the best
resources live.

### Search Sequence

Run these searches. Adapt `{topic}` to the actual topic.

```
SEARCH 1: Overview
  web_search: "{topic} getting started guide"
  Purpose: Find the entry point that experts recommend

SEARCH 1: OFFICIAL DOCUMENTATION (ALWAYS FIRST)
  web_search: "{topic} official documentation"
  OR if you know the docs URL: web_fetch it directly
  Purpose: Official docs are the GROUND TRUTH. Everything else is secondary.
  
  PRIORITY ORDER for finding official docs:
  ├── Known URL (e.g., https://playwright.dev/docs, https://react.dev)
  ├── "{topic} official docs" search
  ├── "{topic} documentation site"
  └── GitHub repo → look for docs link in README
  
  ALWAYS web_fetch the official docs. Read them BEFORE anything else.
  If official docs exist, they override ALL other sources for:
  - API signatures, method names, parameters
  - Installation instructions
  - Configuration options
  - Current version and changelog

SEARCH 2: Academic source (for CS/math/science/engineering)
  web_search: "site:ocw.mit.edu {topic}"
  Purpose: Find MIT's proven teaching structure
  See: references/mit-ocw.md for course directory
  Skip for: framework/tool-specific topics (official docs are better)

SEARCH 3: Concept inventory  
  web_search: "{topic} key concepts beginners"
  Purpose: Discover what the community considers foundational

SEARCH 4: Common mistakes
  web_search: "{topic} common mistakes misconceptions"
  Purpose: Gold for teaching — real pitfalls from real learners

SEARCH 5: Comparisons (if applicable)
  web_search: "{topic} vs {alternative}"
  Purpose: Comparison points help build analogies
```

### Fetch the Best Sources

**Official docs FIRST, then supplement:**

```
FETCH ORDER (this order matters):
1. web_fetch: [OFFICIAL DOCS URL]        → Read FIRST, this is ground truth
2. web_fetch: [MIT OCW syllabus URL]     → Teaching structure (if academic topic)
3. web_fetch: [best tutorial URL]        → Supplement gaps in official docs
4. web_fetch: [misconceptions article]   → Real pitfalls from real learners

RULE: If official docs and a blog post disagree → official docs WIN.
RULE: If official docs and Stack Overflow disagree → official docs WIN.
RULE: If official docs are unclear → search for clarification, but
      always verify against official docs before teaching.
```

**IMPORTANT**: Use `web_fetch` to get the FULL page content.
Search snippets are too short to learn from. You need to READ the actual pages.

### Extract: Survey Output

After Phase 1, you should have this filled in:

```
SURVEY RESULTS:
├── Topic: [name]
├── One-sentence summary: [what it is and why it matters]
├── Core concepts (5-10): [list with brief description each]
├── Prerequisites: [what the learner needs to already know]
├── Recommended learning order: [sequence from MIT/authoritative source]
├── Best resources found:
│   ├── Official docs: [URL]
│   ├── MIT OCW course: [course number + URL] (if applicable)
│   ├── Best tutorial: [URL + why it's good]
│   └── Best video: [URL]
├── Common misconceptions: [2-5 real ones from search results]
├── Community: [GitHub repos, forums, Discord if found]
├── Current version/state: [latest version, recent changes]
└── Size assessment: SMALL / MEDIUM / LARGE
    → If LARGE: generate a ROADMAP (see references/roadmap-builder.md)
```

---

## Phase 2: DEEP DIVE — Focused Research (15-30 min)

Goal: Build deep knowledge on the specific concepts you'll teach.
Only run this for MEDIUM and LARGE topics.

### Identify Focus Areas

From Phase 1's concept list, identify which concepts you'll actually teach
in this session (you can't teach everything at once):

```
For interactive teaching: Pick the first 3-5 concepts in the learning order
For course building: Cover all concepts but group into tutorials
```

### Search Sequence (Per Focus Area)

For EACH focus area, run targeted searches:

```
FOCUS AREA: [concept name]

SEARCH 1: Deep explanation
  web_search: "{topic} {concept} explained"
  Purpose: Find the clearest explanation

SEARCH 2: Practical usage
  web_search: "{topic} {concept} example tutorial"
  Purpose: Find runnable examples

SEARCH 3: Official reference
  web_search: "{topic} {concept} documentation"
  OR web_fetch the relevant section of docs you found in Phase 1
  Purpose: Get the authoritative, current details

SEARCH 4: Pitfalls
  web_search: "{topic} {concept} common mistakes"
  Purpose: What goes wrong with THIS specific concept
```

### Fetch and Deep Read

For each focus area, fetch and READ the best source:

```
web_fetch: [best explanation page]  → Read fully, extract key insight
web_fetch: [official docs section]  → Verify API/syntax is current
web_fetch: [tutorial with examples] → Find the best runnable examples
```

### Extract: Deep Dive Output

For each concept you'll teach:

```
DEEP DIVE — Concept: [name]

├── Key insight: [the ONE thing that makes it click]
├── How it works (mechanism): [2-3 sentences]
├── Why it exists (motivation): [what problem does it solve]
├── Best example found: [code/equation/experiment from sources]
├── Best analogy idea: [what everyday thing is this like]
├── Prerequisites: [what must the learner know first]
├── Common mistakes:
│   ├── Mistake 1: [what they do wrong] → [why] → [fix]
│   └── Mistake 2: [what they do wrong] → [why] → [fix]
├── Checkpoint question: [how to verify they understood]
├── Current API/syntax: [verified from official docs]
└── Connects to: [which other concepts this relates to]
```

---

## Parallel Deep Dive (for Course Building or Large Topics)

When building a course or dealing with a large topic, you can parallelize
Phase 2 across multiple concept areas:

```
PARALLEL EXECUTION:

If subagents/parallel execution is available:
  Agent 1: Deep dive on Concepts 1-3
  Agent 2: Deep dive on Concepts 4-6
  Agent 3: Deep dive on Concepts 7-9
  → Each agent runs the Phase 2 search sequence independently
  → Combine results into unified deep dive output

If sequential only:
  Run Phase 2 for each focus area one at a time
  Prioritize: teach the first 3-5 concepts deeply,
  research the rest at survey level
```

---

## Phase 3: SYNTHESIS — Connect Everything (5-10 min)

After Survey and Deep Dive, synthesize into a teaching-ready knowledge base.

```
SYNTHESIS CHECKLIST:

□ CONCEPT MAP drawn (what depends on what)
□ LEARNING ORDER confirmed (matches MIT/authoritative source)
□ For each concept I'll teach:
  □ Key insight identified
  □ Best example selected (from sources, not from memory)
  □ Analogy drafted
  □ Mistake card prepared
  □ Checkpoint question written
□ GAPS identified (what I couldn't find good sources for)
□ TRACK DECISION noted (does this topic need math? what level?)
□ SIZE ASSESSED:
  □ If SMALL → ready to teach
  □ If MEDIUM → ready to teach (first session covers 3-5 concepts)
  □ If LARGE → ROADMAP generated (references/roadmap-builder.md)
```

---

## Pipeline Timing Guide

```
/teach-me async/await          → Phase 1 only (5 min)  → teach
/teach-me React hooks          → Phase 1 (10 min) + Phase 2 on hooks (15 min) → teach
/teach-me quantum physics      → Phase 1 (15 min) + Phase 2 (30 min) + ROADMAP → teach first module
/teach-me ML --course          → Phase 1 (15 min) + Phase 2 parallel (30 min) + ROADMAP → build course
```

## Example: Quantum Physics Pipeline Run

```
Phase 1 SURVEY:
  web_search: "quantum physics getting started guide"
  web_search: "quantum physics key concepts beginners"
  web_search: "site:ocw.mit.edu quantum physics"          → Found MIT 8.04
  web_search: "quantum physics common misconceptions"
  web_search: "quantum physics vs classical physics"
  
  web_fetch: MIT 8.04 syllabus → Topic order discovered:
    Part 1: Linearity, complex numbers, photons, waves
    Part 2: Schrödinger equation, potentials, tunneling
    Part 3: 3D, angular momentum, hydrogen atom
  
  web_fetch: misconceptions article → Found 4 major ones
  
  SIZE ASSESSMENT: LARGE (22 lectures at MIT = 40+ hours)
  → Must generate ROADMAP (references/roadmap-builder.md)
  → For this session: teach Part 1 concepts only (4-5 concepts)

Phase 2 DEEP DIVE (on Part 1 only):
  Focus 1: "Why classical physics breaks"
    web_search: "photoelectric effect explained simply"
    web_fetch: MIT 8.04 Lecture 3 notes
    → Key insight: energy comes in packets (quanta), not continuous waves
    → Analogy: radio dial (continuous) vs light switch (discrete)
    
  Focus 2: "Wave-particle duality"
    web_search: "double slit experiment explained"
    web_fetch: MIT 8.04 Lecture 4 notes
    → Key insight: not "sometimes wave, sometimes particle" but "always BOTH"
    → Analogy: actor playing two roles in the same movie
    
  Focus 3: "Superposition"
    web_search: "quantum superposition explained not Schrödinger cat"
    → Key insight: state is undefined (not "both at once")
    → Analogy: spinning coin (not heads AND tails — spinning)
    → Misconception: "the cat IS alive and dead" — no, Schrödinger's
      point was that this is ABSURD when applied to big objects

Phase 3 SYNTHESIS:
  Concept map: classical-fails → wave-particle → superposition → measurement
  Track: conceptual (unless learner confirms calculus)
  Ready to teach Part 1. Roadmap generated for full topic.
```