Teach Me

# Student Model — Knowing Your Learner

A teacher who teaches the same way to every student is a bad teacher.
This reference defines how to build, maintain, and use a model of each
individual learner — their level, goals, struggles, and progress.

## What's Missing Without a Student Model

```
WITHOUT student model:
  Session 1: "What's your background?" → teaches quantum basics
  Session 2: "What's your background?" → asks the SAME questions
             → doesn't remember they struggled with superposition
             → doesn't remember they're a visual learner
             → starts from scratch every time

WITH student model:
  Session 1: Learns about the student → saves profile
  Session 2: Loads profile → "Last time we got through wave-particle
             duality and you said superposition was confusing. Let's
             start there with a different analogy."
```

## Folder Structure

```
students/
└── {student-id}/
    ├── profile.json          ← Who they are, what they know
    ├── progress.json         ← What they've learned, per topic
    ├── struggles.json        ← What they got wrong, patterns
    ├── sessions/             ← Session logs for continuity
    │   ├── 2026-04-09.json
    │   └── 2026-04-10.json
    └── roadmaps/             ← Their personal roadmap progress
        └── quantum-physics.json
```

## profile.json — Who Is This Learner?

Build this in Phase 1 (Orient) of the first session, update over time:

```json
{
  "student_id": "derived-from-context",
  "first_session": "2026-04-09",
  "background": {
    "math_level": "calculus",
    "programming": "intermediate python",
    "domain_knowledge": "basic classical physics",
    "education": "undergrad CS student"
  },
  "learning_preferences": {
    "track": "mathematical",
    "pace": "medium",
    "style": "visual",
    "prefers_analogies": true,
    "prefers_code_examples": true,
    "prefers_derivations": false
  },
  "goals": [
    "Understand quantum computing prerequisites",
    "Pass intro QM course"
  ],
  "notes": "Visual learner — diagrams and simulations work best. Gets confused by pure notation without pictures."
}
```

### How to Build the Profile

```
SESSION 1 — gather through conversation (don't interrogate):

ESSENTIAL (ask directly):
  "What's your background with [topic]?"
  "What's your math comfort level?"
  "What made you want to learn this?"

OBSERVE (detect from responses):
  Pace: Do they answer quickly (speed up) or slowly (slow down)?
  Style: Do they respond to analogies ("oh, like a...") or to code/math?
  Depth: Do they ask "why?" (wants depth) or "what next?" (wants breadth)?

SESSION 2+ — update, don't re-ask:
  Load profile → use it → update based on new observations
```

## progress.json — What Have They Learned?

Track per-topic progress across sessions:

```json
{
  "quantum-physics": {
    "roadmap_module": 1,
    "sessions_completed": 3,
    "concepts_mastered": [
      {
        "concept": "photoelectric-effect",
        "status": "mastered",
        "checkpoint_passed": true,
        "session": "2026-04-09"
      },
      {
        "concept": "superposition",
        "status": "partial",
        "checkpoint_passed": false,
        "notes": "Understands the math but still thinks 'both states at once'",
        "session": "2026-04-09"
      }
    ],
    "current_position": "wavefunctions",
    "last_session": "2026-04-10",
    "total_time_minutes": 75
  }
}
```

### Status Levels

```
"introduced"  — concept was mentioned but not fully taught
"taught"      — full explanation given, example shown
"partial"     — checkpoint attempted, partially correct
"mastered"    — checkpoint passed, can explain in own words
"reinforced"  — revisited in later context, still solid
```

## struggles.json — Where They Get Stuck

Track error PATTERNS, not just individual mistakes:

```json
{
  "patterns": [
    {
      "type": "misconception",
      "concept": "superposition",
      "description": "Thinks particle IS in both states simultaneously",
      "occurrences": 2,
      "correction_attempted": "spinning coin analogy",
      "resolved": false,
      "notes": "May need a completely different analogy — try the polarization filter approach next time"
    },
    {
      "type": "prerequisite_gap",
      "concept": "wavefunctions",
      "description": "Uncomfortable with complex numbers",
      "occurrences": 1,
      "action_taken": "Quick intro to complex plane",
      "resolved": true
    },
    {
      "type": "pacing",
      "description": "Gets overwhelmed when more than 2 new ideas per message",
      "action": "Keep to 1 concept per message, shorter messages"
    }
  ]
}
```

## Session Logs — Continuity Across Sessions

After each session, save a brief log:

```json
{
  "session_id": "2026-04-09-quantum",
  "date": "2026-04-09",
  "topic": "quantum-physics",
  "duration_minutes": 25,
  "concepts_covered": [
    "why-classical-breaks",
    "wave-particle-duality",
    "superposition"
  ],
  "checkpoints": {
    "photoelectric": "passed",
    "double-slit": "passed",
    "superposition": "partial — still conflates with 'both at once'"
  },
  "what_worked": [
    "Radio dial vs light switch analogy — clicked immediately",
    "Showing the double-slit video helped more than the diagram"
  ],
  "what_didnt_work": [
    "Spinning coin analogy for superposition — they kept saying 'but the coin IS heads or tails underneath'"
  ],
  "next_session_plan": "Try polarization filter approach for superposition, then move to measurement and wavefunctions",
  "homework": "Watch MIT 8.04 Lecture 1 video, try to predict what happens in a Mach-Zehnder interferometer"
}
```

---

## The Full Teacher-Student Workflow

Here's everything that was missing, now included:

```
COMPLETE WORKFLOW:

┌─────────────────────────────────────────────────┐
│  BEFORE FIRST SESSION (teacher prepares)        │
│                                                 │
│  1. Check knowledge store                       │
│     knowledge/{topic}/ exists?                  │
│     YES → check freshness → refresh if stale    │
│     NO  → run learning pipeline → save to store │
│                                                 │
│  2. Load or create student profile              │
│     students/{id}/profile.json exists?          │
│     YES → load profile + progress + struggles   │
│     NO  → will build in Phase 1 (Orient)        │
│                                                 │
│  3. Plan session using stored knowledge +       │
│     student model (Stages 3-5)                  │
│     → Adjust for THIS student's level/struggles │
│     → Skip concepts they've mastered            │
│     → Focus on concepts they struggled with     │
│                                                 │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  DURING SESSION (teaching)                      │
│                                                 │
│  Phase 1: Orient                                │
│     Returning? → "Last time we covered X.       │
│       You were working on understanding Y.      │
│       Ready to continue?"                       │
│     New? → Build profile through conversation   │
│                                                 │
│  Phase 2: Build                                 │
│     → Teach using stored teaching-notes.md      │
│     → Track checkpoints (pass/fail/partial)     │
│     → Note which analogies work for THIS student│
│     → If stuck → check struggles.json for       │
│       patterns, try a different approach         │
│                                                 │
│  Phase 3: Apply                                 │
│     → Challenge calibrated to their level       │
│     → Track performance                         │
│                                                 │
│  Phase 4: Solidify                              │
│     → Recap + resources                         │
│     → Assign HOMEWORK (practice between sessions│
│     → Preview what's next                       │
│                                                 │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  AFTER SESSION (teacher reflects + saves)        │
│                                                 │
│  1. Update student model                        │
│     → progress.json: mark concepts covered      │
│     → struggles.json: record error patterns     │
│     → profile.json: update preferences observed │
│                                                 │
│  2. Save session log                            │
│     → What was taught, checkpoints, what worked │
│     → Next session plan                         │
│                                                 │
│  3. Update knowledge store (if improved)        │
│     → Better analogy found? Save it             │
│     → New misconception discovered? Add it      │
│     → Better example emerged? Replace old one   │
│                                                 │
│  4. Assign homework                             │
│     → Specific practice for their weak areas    │
│     → "Watch this video" / "Try this problem"   │
│     → "Explain [concept] to a friend"           │
│                                                 │
└─────────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────────┐
│  RETURNING SESSION (continuity)                  │
│                                                 │
│  1. Load everything: knowledge + student + logs │
│  2. Quick review: "Can you still explain [X]?"  │
│     → If yes: proceed to new material           │
│     → If no: brief reinforcement, then proceed  │
│  3. Check homework if assigned                  │
│  4. Continue from where they left off           │
│  5. Spaced review: revisit earlier concepts     │
│     in new contexts every 3-5 sessions          │
│                                                 │
└─────────────────────────────────────────────────┘
```

## Spaced Review Schedule

Don't just teach forward — reinforce backward:

```
Session 1: Teach A, B
Session 2: Quick review A → Teach C, D
Session 3: Teach E, F (A is reinforced naturally if E builds on A)
Session 4: Quick review B, C → Teach G
Session 5: REVIEW SESSION — revisit A-D in new context/problems
Session 6: Teach H, I

Rule: Every 4-5 sessions, one session should be primarily review
      with harder problems that combine earlier concepts.
```

## Homework Design

```
HOMEWORK TYPES:

WATCH: "Watch MIT 8.04 Lecture 3 (18 min). Note one thing that surprises you."
  → Low effort, builds familiarity, primes for next session

READ: "Read this section of the docs. Write down 2 questions."
  → Forces active reading, surfaces confusion BEFORE the session

PRACTICE: "Solve problems 1-3 from this problem set."
  → Skill building, reveals gaps
  → Always provide solutions they can check against

EXPLAIN: "Explain [concept] to a friend or write a paragraph explaining it."
  → Feynman technique — best test of understanding

BUILD: "Modify the simulation we built to show [variation]."
  → Extends session work, creative application

PREDICT: "Before next session, predict what happens when [scenario]."
  → Creates anticipation, activates prior knowledge
```

## Assessment Without Tests

Real understanding shows up in these ways — track them:

```
CAN THEY EXPLAIN IT? (Feynman test)
  "In your own words, why does [X] work this way?"
  → If they can explain simply → they understand
  → If they use jargon without meaning → surface-level

CAN THEY PREDICT? (transfer test)
  "What do you think happens if we change [parameter]?"
  → If they predict correctly → they have the mental model
  → If they guess randomly → they memorized, not understood

CAN THEY DEBUG? (deep test)
  "This reasoning/code has an error. Can you find it?"
  → If they spot it → they understand the constraints
  → If they can't → they know WHAT but not WHY

CAN THEY TEACH? (ultimate test)
  "How would you explain [X] to someone who doesn't know it?"
  → If they find a good analogy → they truly get it
```