Teach Me

# Course Builder Pipeline

This reference covers the full course generation workflow.
Read this when the user explicitly asks for a course (`--course` flag).

## Overview

```
Source → Analyze → Outline → Write → Quality Check → Deliver
```

## Step 1: Analyze the Source

### From a Code Repository

Read the repo. Produce a structured knowledge map:

1. **File inventory** — classify each file:
   - `core`: Main logic, models, routes, services
   - `supporting`: Helpers, utils, config, types
   - `peripheral`: Tests, CI, docs, lockfiles

2. **Architecture map**:
   - Entry points (main.go, index.ts, app.py)
   - Data/request flow from entry to output
   - Dependency graph (imports/requires)
   - Layers (HTTP → service → repo → database)

3. **Concept extraction** — for each concept:
   - Name (e.g., "middleware chain", "repository pattern")
   - Complexity rating: 1 (beginner) → 5 (expert)
   - Files that demonstrate it
   - Prerequisites (concepts that must come first)
   - Key patterns used

4. **Learning order** — optimal teaching sequence

### From a Documentation Site

Crawl/read the docs. Produce:

1. **Site map** — full navigation hierarchy
2. **Page classification**:
   - `essential`: Core concepts every user must know
   - `practical`: How-to guides, common tasks
   - `reference`: API docs, config options
   - `advanced`: Edge cases, performance, plugins
   - `skip`: Changelog, contributing, deprecated

3. **Concept extraction** — same as repo, plus:
   - Source page URLs
   - Best code example from docs
   - Docs gap: what this page explains poorly

4. **Gap analysis** — what the docs do badly:
   - Concepts mentioned but never fully explained
   - Missing connections between separate pages
   - No learning progression (it's reference, not tutorial)
   - Assumed knowledge beginners won't have
   - Information scattered across pages that should be unified

5. **Learning order** — progressive sequence

### From a Topic (no source)

1. **Search MIT OCW first** for academic/CS/math/engineering topics:
   - `web_search "site:ocw.mit.edu [topic]"`
   - If a course exists: fetch the syllabus for topic ordering, lecture notes for content
   - Use MIT's proven teaching progression as a foundation
   - Extract problem sets for challenge design
2. Research the topic via web search (current tutorials, official docs)
3. Break into teachable concepts with complexity ratings
4. Map prerequisites and dependencies
5. Design a progressive project learners will build
6. **Verify OCW content is current** — for CS fundamentals it always is,
   for tools/frameworks prefer official docs instead

### Output Format

Store the analysis as JSON. Schema in `references/analysis-schema.md`.

---

## Step 2: Design the Course Outline

Group concepts into tutorials (15-45 minutes each).

### Progression Arc

```
Tutorial 1:  "What and Why"     — What is this? Why does it matter? Big picture.
Tutorial 2:  "Hello World"      — Install, setup, first working thing (< 5 min to "it works!")
Tutorial 3+: "Build Up"         — Layer by layer, simple → complex
Final:       "Full Picture"     — Connect everything, real-world walkthrough
```

### Tutorial Sizing

- Target: 15-45 minutes per tutorial
- ONE primary concept per tutorial
- Supporting concepts are OK but don't take focus
- Must end with a runnable, verifiable milestone

### For Docs-Sourced Courses, Additionally:

- Map each tutorial to source docs pages
- Specify what each tutorial adds BEYOND the docs
- Identify which docs gaps each tutorial fills
- Design a progressive project (the docs won't have one)

### Outline Specification

For each tutorial, define:
- Title (action-oriented: "Write Your First Test" not "Testing Basics")
- Primary concept(s) with IDs
- Prerequisite tutorials
- Estimated time
- Key files/pages referenced
- Milestone (what learner can DO after)
- Challenge (stretch exercise)
- (Docs) Source pages + what this adds beyond docs

---

## Step 3: Write Tutorials

### Apply the Teaching Methodology

Every tutorial MUST follow these principles from the main SKILL.md:

1. **WHY before HOW** — explain motivation before mechanics
2. **Show, Then Explain** — code first, explanation after
3. **Analogies** — every new concept gets one
4. **Progressive Complexity** — simple version first, add layers
5. **Common Mistakes** — wrong vs right with explanation
6. **Runnable Milestones** — end with something verifiable
7. **Scaffolded Challenges** — extend, don't repeat
8. **Contextual Bridges** — connect to previous and next tutorials

### Tutorial Section Order

Every tutorial must include these sections in this order:

```
1. HEADER
   - Number + title (action-oriented verb)
   - Time estimate, difficulty badge, prerequisites

2. DOCS REFERENCE (docs-sourced only)
   - Link to official docs page(s)
   - "We go deeper by..."

3. WHAT YOU'LL LEARN
   - 3-5 concrete skills
   - ❌ "Learn about testing"
   - ✅ "Write a test that mocks API responses and verifies error handling"

4. WHY THIS MATTERS
   - Real-world scenario
   - Connection to previous/next tutorials
   - What problem this solves

5. WALKTHROUGH
   - Steps with action-verb headers
   - Code with file path labels
   - Code FIRST, explanation AFTER
   - Reference real files/lines

6. COMMON MISTAKES (at least 1, ideally 2-3)
   - Wrong code vs right code
   - WHY the mistake is bad

7. TRY IT YOURSELF
   - Extends the tutorial (not a repeat)
   - Specific + achievable
   - Collapsible hint + optional solution

8. KEY TAKEAWAYS
   - 3-5 transferable principles
   - Mental models, not just syntax

9. WHAT'S NEXT
   - 1-2 sentences bridging to next tutorial

10. FURTHER READING (optional)
    - Official docs links, blog posts, deep dives
```

### Progressive Project Requirement

ALL tutorials must build ONE continuous project:

```
❌ Tutorial 1: Random example A
   Tutorial 2: Completely different example B
   Tutorial 3: Yet another isolated example C

✅ Tutorial 1: Set up the project, get it running
   Tutorial 2: Add first feature to the project
   Tutorial 3: Extend that feature with auth
   Tutorial 4: Add error handling to what we built
   Tutorial 5: Test everything we've created
```

### Progressive Artifact (Non-Code Topics)

For topics without a codebase (physics, math, history, biology), replace
"progressive project" with a **progressive artifact** — something tangible
the learner builds across tutorials:

| Domain | Artifact | Example |
|--------|----------|---------|
| **Physics** | Python/JS simulation | Quantum particle-in-a-box sim that gains features each tutorial: wavefunction plot → probability density → energy levels → tunneling |
| **Mathematics** | Visualization notebook | Jupyter/Observable notebook: plot functions → add interactivity → build to proof visualization |
| **Algorithms** | Working implementation | Build a search engine: tokenizer → index → ranking → query optimization |
| **Machine Learning** | Model pipeline | Dataset → preprocessing → model → evaluation → deployment |
| **History** | Annotated interactive timeline | Add events, causes, connections each tutorial — ends as a navigable map |
| **Biology** | System diagram + simulation | Cell diagram → metabolic pathways → gene expression → interactive model |
| **Electronics** | Circuit simulation | LED → amplifier → filter → oscillator, each tutorial adds a stage |
| **Economics** | Economic model | Supply/demand → market equilibrium → policy simulation → game theory |

**The artifact serves the same purposes as a code project:**
- Each tutorial adds to it (continuity)
- The learner has something to VERIFY after each tutorial
- It compounds — later tutorials build on earlier work
- It's something they can show people ("look what I built")

**For courses with HTML interactive output:** embed the artifact directly
into the course. A quantum physics course could include an interactive
wavefunction visualization that gains features as the learner progresses.

---

## Step 4: Quality Check

Before delivering, verify:

- [ ] No tutorial references a concept not yet taught
- [ ] Every tutorial ends with a runnable, verifiable milestone
- [ ] Difficulty increases gradually (no sudden jumps)
- [ ] Progressive project/artifact builds naturally across tutorials
- [ ] Every tutorial has Common Mistakes section
- [ ] Code blocks have file path labels
- [ ] Code shown BEFORE explanation
- [ ] WHY explained before HOW
- [ ] Challenges extend (not repeat) the walkthrough
- [ ] Bridges connect previous AND next tutorials
- [ ] (Docs) No section merely restates official docs
- [ ] (Docs) Identified gaps are filled
- [ ] (STEM) Math rendering works — KaTeX included if equations are present
- [ ] (STEM) Equations have plain-English translations alongside
- [ ] (STEM) Track is appropriate for audience (conceptual vs mathematical)
- [ ] (STEM) Interactive visualizations included where they build intuition
- [ ] Total time is reasonable

---

## Step 5: Output Format

Read the appropriate format reference BEFORE writing:

| Format | Flag | Reference | Best For |
|--------|------|-----------|----------|
| Markdown | `--format=md` | `references/format-markdown.md` | Wikis, Notion, READMEs |
| Interactive HTML | `--format=html` (default) | `references/format-html-interactive.md` | Standalone, workshops |
| GitHub Pages | `--format=jekyll` | `references/format-github-pages.md` | Hosted course sites |

If no format specified, default to `html` (best standalone experience).