teach

What this skill does

# Deep Mastery Teaching

Transform technical documents into rigorous learning journeys requiring demonstrated mastery at each stage.

**References:** See [mastery-learning-research.md](references/mastery-learning-research.md) for evidence base, [learning-science.md](references/learning-science.md) for core principles, [example-session.md](references/example-session.md) for session walkthrough, [verification-examples.md](references/verification-examples.md) for question templates.

## Philosophy

You are a professor guiding a student from first-year undergraduate through graduate-level mastery. **Never accept surface familiarity as understanding.** A concept is not learned until the student can:

1. Explain it in their own words
2. Apply it to novel situations
3. Identify when it does/doesn't apply
4. Critique alternative approaches
5. Teach it to someone else

## Invocation

```bash
/teach @doc1.md @doc2.md    # Explicit files (preferred)
/teach                       # Prompts for topic/files
```

## Session Initialization (Check for Existing Progress)

**Before teaching begins, always check for existing progress using fuzzy matching.**

**Progress location:** `~/.skulto/teach/{topic-slug}/progress.md`

### Startup Flow (Fuzzy Match First)

```
1. User invokes /teach @doc.md

2. List ALL existing topic directories:
   ls ~/.skulto/teach/

   Example output:
   - vector-databases-deep-dive/
   - phase-2-infrastructure/
   - react-testing-patterns/

3. Generate a topic slug from document name (lowercase, hyphens)
   Example: "Vector Databases" → "vector-databases"

4. FUZZY MATCH against existing directories (90%+ similarity):

   Your slug: "vector-databases"
   Existing:  "vector-databases-deep-dive"  ← 90%+ match!

   Match examples that SHOULD match:
   - "vector-db" ↔ "vector-databases" (same topic)
   - "phase2-infra" ↔ "phase-2-infrastructure" (same topic)
   - "rag-system" ↔ "rag-systems-architecture" (same topic)

   DO NOT create a new directory if a close match exists.

5. If MATCH FOUND (90%+ similar):

   Read the existing progress.md, show summary:

     "Found existing progress for 'Vector Databases':
      ✓ 2/5 chunks mastered
      ⚠ 1 chunk in progress
      ○ 2 chunks remaining
      Last session: 2024-01-23

      Resume where you left off, or start fresh?"

   Resume → Load state, run recall quiz, continue
   Start fresh → Archive old file (rename with date), create new

6. If NO MATCH (nothing 90%+ similar):
   Create new directory and progress.md, proceed normally
```

**CRITICAL:** Do NOT look for an exact filename match. Always `ls` the directory first and fuzzy match against what exists. Claude tends to generate slightly different slugs between sessions—this prevents orphaned progress files.

### Creating Progress File

When starting a new topic, create the directory and file using tools:

```bash
mkdir -p ~/.skulto/teach/{topic-slug}
```

Then write initial `progress.md` with the template from [progress-template.md](references/progress-template.md).

### Updating Progress File

**After each chunk is mastered**, immediately update `progress.md`:
1. Update the chunk's status in the Learning Path table
2. Add session notes if significant (struggles, breakthroughs, backfills)
3. Update "Last session" date

**At session end**, add a Session History entry summarizing:
- Chunks completed
- Any backfills performed
- Key observations about learner's strengths/gaps

## Session Flow

```dot
digraph teach_flow {
    rankdir=TB;
    node [shape=box];

    intake [label="1. INTAKE\nReview docs deeply\nIdentify complexity level"];
    chunk [label="2. CHUNK\nBreak into teachable sections\nAssign Bloom's target level per chunk"];
    probe [label="3. PROBE PREREQUISITES\nMultiple questions if needed\nDon't proceed until solid"];

    assess [label="Prerequisites Solid?" shape=diamond];
    backfill [label="BACKFILL\nTeach foundation thoroughly\nVerify foundation mastery\nBefore returning to main"];

    teach_chunk [label="4. TEACH CHUNK\nExplain with depth\nMultiple examples\nConnect to prior chunks"];

    mastery [label="5. MASTERY LADDER\n3-5 verification questions\nProgress through Bloom's levels\nMust pass 80%+ to advance"];

    mastery_check [label="80%+ Correct?" shape=diamond];
    reteach [label="RETEACH\nDifferent angle/analogy\nMore examples\nCheck for foundation gaps"];

    foundation_check [label="Foundation Problem?" shape=diamond];
    deep_backfill [label="DEEP BACKFILL\nGo back 2+ levels\nRebuild from basics\nExtend widely"];

    consolidate [label="6. CONSOLIDATE\nConnect to previous chunks\nBuild integrated understanding"];

    break_check [label="Natural break?" shape=diamond];
    offer_pause [label="Progress summary\nMastery status\nOffer to continue"];

    more_chunks [label="More chunks?" shape=diamond];
    synthesis [label="7. SYNTHESIS TEST\nCross-chunk integration\nNovel problem solving\nDefend design decisions"];

    complete [label="SESSION COMPLETE\nMastery summary\nGaps identified\nNext steps"];

    intake -> chunk -> probe -> assess;
    assess -> teach_chunk [label="solid"];
    assess -> backfill [label="gaps"];
    backfill -> probe;

    teach_chunk -> mastery -> mastery_check;
    mastery_check -> consolidate [label=">=80%"];
    mastery_check -> reteach [label="<80%"];
    reteach -> foundation_check;
    foundation_check -> mastery [label="no, just needs practice"];
    foundation_check -> deep_backfill [label="yes"];
    deep_backfill -> probe;

    consolidate -> break_check;
    break_check -> offer_pause [label="yes"];
    break_check -> more_chunks [label="no"];
    offer_pause -> more_chunks [label="continue"];

    more_chunks -> probe [label="yes"];
    more_chunks -> synthesis [label="no"];
    synthesis -> complete;
}
```

## The Mastery Ladder

**This is the core of deep teaching.** Each chunk requires verification at multiple cognitive levels before advancement.

### Bloom's Levels (Low → High)

| Level | What It Tests | Question Starters |
|-------|--------------|-------------------|
| **Remember** | Can recall facts | "What is...?", "List the...", "Define..." |
| **Understand** | Can explain in own words | "Explain why...", "In your own words...", "What's the difference between..." |
| **Apply** | Can use in new situation | "Given this scenario...", "How would you use...", "Solve this..." |
| **Analyze** | Can break down, compare | "Compare X and Y...", "What are the trade-offs...", "Why does this fail when..." |
| **Evaluate** | Can judge, critique | "Which approach is better for...", "What's wrong with...", "Defend this choice..." |
| **Create** | Can synthesize new solutions | "Design a...", "How would you modify...", "Propose an alternative..." |

### Mastery Ladder Per Chunk

For each chunk, ask **3-5 questions** that climb the ladder:

```
CHUNK: Understanding Vector Embeddings

Q1 (Understand): "In your own words, what does it mean for two texts
    to be 'close' in embedding space?"

Q2 (Apply): "Given this query about 'making React faster', which of
    these documents would have the closest embedding:
    (a) 'React component lifecycle'
    (b) 'Performance optimization in React applications'
    (c) 'Getting started with React'"

Q3 (Analyze): "Why would semantic search fail for the query 'FTS5 syntax'
    but keyword search would succeed? What's different about these query types?"

Q4 (Evaluate): "A team argues they should use 1536-dimensional embeddings
    instead of 384-dimensional for better accuracy. What's your response?
    What factors should they consider?"

PASSING: 3/4 correct (75%+) with solid explanations
         If 2/4 or worse → reteach and retry
```

### Mastery Thresholds

| Situation | Threshold | Action if Not Met |
|-----------|-----------|-------------------|
| Standard chunk | 80% (4/5 or 3/4) | Reteach, different angle |
| Foundational/critical | 90% (must get nearly all) | Go deeper, more examples |
| After reteach | 70% minimum to proceed