teach-me

name: teach-me description: Incremental teaching skill — ensures deep understanding of any topic through restating, quizzing, and comprehension gates before moving on. Supports full mode (HTML lesson pages with in-browser quiz) and simple mode (chat-only).

Teach Me

Overview

An incremental teaching skill that ensures deep understanding by requiring the human to restate concepts, quizzing, and refusing to advance until mastery is confirmed at each stage.

Invoke as: /teach-me <topic or git commit or PR or concept>

On every invocation, ask mode via AskUserQuestion before doing anything else:

Options:

• Full mode — I'll generate a styled lesson page that opens in your browser for each phase. You take the quiz there and report your score back here. Files are saved so you can revisit later.
• Simple mode — Everything stays in this chat. Quiz uses interactive multiple-choice questions here. No files generated beyond a checklist.

Flow (Full Mode)

digraph teach_me_full {
    "User invokes /teach-me" -> "Ask mode (AskUserQuestion)";
    "Ask mode (AskUserQuestion)" -> "Simple mode path" [label="simple"];
    "Ask mode (AskUserQuestion)" -> "Scope topic + create session dir" [label="full"];
    "Scope topic + create session dir" -> "Restate gate (chat)";
    "Restate gate (chat)" -> "Generate phase-N.html + open in browser";
    "Generate phase-N.html + open in browser" -> "User takes quiz in browser";
    "User takes quiz in browser" -> "User reports score in chat";
    "User reports score in chat" -> "Score >= 80%?" [label="gate"];
    "Score >= 80%?" -> "Update session.md [x], next phase" [label="yes"];
    "Score >= 80%?" -> "Ask which Qs missed, reteach, regenerate HTML" [label="no"];
    "Update session.md [x], next phase" -> "All 3 phases done?";
    "All 3 phases done?" -> "Session complete" [label="yes"];
    "All 3 phases done?" -> "Restate gate (chat)" [label="no"];
}

Flow (Simple Mode)

digraph teach_me_simple {
    "Simple mode" -> "Scope topic + create teach-me-session.md";
    "Scope topic + create teach-me-session.md" -> "Phase 1: The Problem";
    "Phase 1: The Problem" -> "Restate check";
    "Restate check" -> "Quiz (AskUserQuestion)";
    "Quiz (AskUserQuestion)" -> "Pass?" [label="gate"];
    "Pass?" -> "Phase 2: The Solution" [label="yes"];
    "Pass?" -> "Reteach + re-quiz" [label="no"];
    "Phase 2: The Solution" -> "Restate check";
    "Restate check" -> "Quiz (AskUserQuestion)";
    "Quiz (AskUserQuestion)" -> "Pass?" [label="gate"];
    "Pass?" -> "Phase 3: Broader Context" [label="yes"];
    "Phase 3: Broader Context" -> "Final quiz";
    "Final quiz" -> "All checklist items [x]?";
    "All checklist items [x]?" -> "Session complete" [label="yes"];
    "All checklist items [x]?" -> "Revisit gaps" [label="no"];
}

Phase 1: Clarify, Mode Selection, and Set Up

0. Check for topic argument — if the user invoked /teach-me with no topic, ask: "What topic, commit, PR, or concept would you like to learn about?" Wait for their answer before proceeding.

1. Ask mode via AskUserQuestion — Full mode vs Simple mode (with the descriptions above). Do this before anything else.

2. Scope the topic — if vague, ask one clarifying question.

3. Set up session files:

   Full mode:

   • Generate a slug: lowercase, hyphens for spaces, max 40 chars (e.g. react-hooks)
   • Check if teach-me-sessions/{slug}-{YYYYMMDD}/session.md exists and contains any [ ] or [~] items. If yes: ask the user — "I found an existing session for this topic. Resume from where you left off, or start fresh?"
     • If resume: read session.md to find the first phase with incomplete items ([ ] or [~]), start the teaching loop from that phase's Step A (restate gate)
     • If fresh: create a new directory with -2/-3 suffix and proceed normally
   • If no existing session: create directory teach-me-sessions/{slug}-{YYYYMMDD}/ (append -2, -3 etc. for same-day collisions)
   • Write teach-me-sessions/{slug}-{YYYYMMDD}/session.md with the concept checklist

   Simple mode:

   • Write teach-me-session.md in the current directory with the concept checklist

4. Tell the user the plan: phases, what mastery means, how gates work.

Full Mode Teaching Loop

Run phases 1→2→3 sequentially. Do not advance until the gate passes.

For each phase:

Step A — Restate gate (chat)

Before generating the HTML, ask the user to explain their current understanding of the phase topic. Assess what's right and what's missing. Fill gaps concisely in chat. This stays in chat for both modes — it's conversational.

Step B — Generate phase HTML

Generate teach-me-sessions/{slug}-{date}/phase-{N}.html using the template at ~/.claude/skills/teach-me/templates/phase.html as structural reference.

What to fill in:

Quiz Generation rules:

• 3–5 questions per phase, mix of multiple-choice and true-false
• correct index: for multiple-choice, never 0 (never option A) — doing so allows pattern-guessing without reading. Vary across 1, 2, 3. Don't use the same index twice in a row across questions.
• explanation: explain why the correct answer is right AND why the main distractors are wrong
• Questions must test understanding of the concepts taught in this phase only

Diagrams: Use a <figure class="diagram"> wrapping an <img> or inline <svg> to include diagrams in the lesson. Add a <figcaption> for labels.

Step C — Open in browser

open "teach-me-sessions/{slug}-{date}/phase-{N}.html"

Tell the user: "Phase {N} is open in your browser. Take the quiz and report your score here."

Step D — Score gate (chat)

Wait for the user to report their score.

Score ≥ 80%:

1. Acknowledge: "Good — X/Y. Moving to Phase {N+1}."
2. Update session.md: mark this phase's concepts [x]
3. Advance to Step A of the next phase

Score < 80%:

1. Ask: "Which questions did you miss?"
2. Reteach only the missed concepts in chat — concise and targeted
3. Tell the user: "Go back to the browser and click Retry quiz to retake it."
4. Return to Step D (wait for new score)

Do NOT regenerate the HTML file. The same page stays open; the "Retry quiz" button resets the quiz state in-browser.

If the user has attempted the same phase quiz 3 or more times without passing: say "We've gone through this a few times — would you like me to slow down and re-explain everything from scratch, or move on and come back to this phase later?" Let the user decide; do not loop indefinitely.

Simple Mode Teaching Loop

This is the original behavior. Run phases 1→2→3 sequentially in chat.

Phase 1 — The Problem

Teach: why this problem existed, the different approaches considered, what made it hard.

Gate (restate): Ask the user to explain in their own words before filling gaps. After they answer, identify what's right, what's missing, fill gaps concisely.

Gate (quiz): Use AskUserQuestion with 2–3 questions (multiple-choice and/or true/false). Randomize correct-answer position — never option A, never the same slot twice in a row. Do not reveal the answer until after submission. After submission, explain why the correct answer is right and why wrong answers are wrong.

≥ 80% correct → advance. < 80% → ask the user which specific questions they missed, then reteach missed concepts only, re-quiz those points. After 3 failed attempts on the same phase, offer to re-explain from scratch or let the user move on voluntarily.

Phase 2 — The Solution

Teach: why this specific solution, key design decisions, edge cases.

Gate: same restate + quiz mechanics as Phase 1.

Phase 3 — Broader Context

Teach: why it matters beyond the immediate fix, what else is impacted, broader patterns.

Gate (final quiz): Mix of multiple-choice and true/false covering all three phases. Must pass ≥ 80%.

Update teach-me-session.md throughout:

• [~] when introduced
• [x] only after the quiz gate passes for that concept

Session ends when all items are [x].

Mechanics

Restate First (both modes)

Always ask the user to explain their current understanding before filling gaps. This surfaces what they already know and prevents passive reading.

AskUserQuestion Format (simple mode)

• Multiple choice: 4 options. Correct answer must NOT be option A (index 0). Vary position across 1, 2, 3. Never the same slot twice in a row.
• True/false: 2 options.
• Never reveal the correct answer in the question text.
• After submission, explain why the correct answer is right and why wrong answers are wrong.

ELI Support (both modes)

Respond to these keywords at any point:

• eli5 → explain like I'm 5
• eli14 → explain like I'm 14
• elii → explain like I'm an intern

Simple mode: give the ELI explanation in chat, then resume the gate immediately. Full mode: the HTML already contains ELI toggles for the current phase. In chat, give a brief ELI explanation and point the user to the "Explain it simpler" toggle in the browser.

Code/Debugger Mode (both modes)

If understanding would benefit from code:

• Show the relevant snippet
• Ask "what do you think this does?" before explaining
• Walk through line by line if asked

Session Completion

When all checklist items are [x]:

1. Show the completed checklist
2. Give a 2-sentence summary of what was mastered
3. Suggest one related topic to explore next

Critical Rules

• Ask mode first — always AskUserQuestion for Full vs Simple before doing anything else
• Never advance a phase without passing the gate — not even if the user says "I get it, move on"
• Never put the correct answer first — position 1, 2, or 3 (0-indexed) only; vary across questions
• Never reveal the answer before submission
• Restate before teaching — always ask what they know first
• If the user asks to skip — acknowledge, explain why the gate exists, offer a faster version of the quiz instead of skipping

Common Mistakes to Avoid