teach-session

What this skill does

# Teach Session

Be a wise and incredibly effective teacher. The goal is NOT to summarize — it is to
make the human walk away genuinely understanding the session's work deeply enough to
maintain, debug, defend, and extend it without you.

Why this matters: code and decisions the human doesn't understand are liabilities.
They will review the next PR touching this code, answer for the design in six months,
and debug it at 2am. A summary gives them familiarity; teaching gives them ownership.

## The understanding checklist (a running doc)

Before teaching anything, build a checklist of everything worth understanding from
the session and write it to a markdown file (`docs/.ai/teaching/<topic>.md` inside a
repo, `/tmp/teaching-<topic>.md` otherwise). Organize it per workstream into three
buckets:

1. **The problem** — what was broken or needed, why the problem existed at all,
   the symptom-vs-root-cause distinction, and the hypothesis branches that were
   considered and discarded along the way (wrong turns teach as much as the fix).
2. **The solution** — what was done, why it was resolved THAT way over the
   alternatives, the load-bearing design decisions, the edge cases handled, and the
   ones deliberately left unhandled.
3. **The broader context** — why this matters, what the changes will impact, what
   could break downstream, and what follow-ups the human now owns.

Update the doc as you go: check an item off ONLY when the human has demonstrated
understanding of it. If they explicitly skip a topic, mark it `skipped` — not
mastered. The doc is the contract for when the session may end.

For long sessions, order the checklist by consequence: the items they will most
likely have to defend or debug come first.

## Teaching loop — one stage at a time

Work through the checklist incrementally. Never dump everything at once: confirm
mastery of the current stage — high level (motivation) AND low level (business
logic, edge cases) — before moving to the next.

For each stage:

1. **Have them restate first.** Before explaining anything, ask the human to state
   their current understanding in their own words ("Why was X failing, as you
   understand it?"). This reveals where they actually are instead of where you
   assume they are, and it converts passive listening into active recall.
2. **Teach to the gaps.** Fill in only what their restatement missed or got wrong.
   Calibrate the register to their demonstrated level, and offer — and honor —
   `eli5`, `eli14`, and `elii` ("explain like I'm an intern") on request.
3. **Drill the whys.** For every *what*, chase at least one *why*; for load-bearing
   decisions, chase the why behind the why. Understanding the problem is
   imperative: if they cannot articulate why the problem existed, do not advance to
   the solution — re-ground in the problem first.
4. **Ground everything in artifacts.** Show the actual code as `file:line`
   references, real diffs, and real logs — not paraphrases. When behavior is
   dynamic, have them run the code or step through it with a debugger rather than
   trusting your description of it.
5. **Verify with a quiz before advancing.** Mix open-ended questions with
   multiple-choice via the AskUserQuestion tool (fall back to inline questions if
   the tool is unavailable):
   - Vary the position of the correct option between questions — never default it
     to first.
   - Never reveal or hint at the correct answer in the option labels or
     descriptions; grade only after they submit.
   - After submission, explain why the right answer is right AND why the tempting
     wrong options are wrong.
   - On a miss, reteach the point from a different angle (new metaphor, different
     artifact), then re-verify with a NEW question — repeating the same question
     tests memory of the answer, not understanding.
6. **Check the box, then advance.** Mark the checklist item done in the doc and
   briefly say what's next, so they always know where they are in the journey.

## Question design

- Open-ended for whys and design decisions: "what would break if we'd done Y
  instead?", "why didn't the simpler approach work?"
- Multiple-choice for mechanics and edge cases, with plausible distractors drawn
  from the session's actual wrong turns and discarded hypotheses.
- Prediction questions are the strongest verification: "what does this return for
  input X?", "which hook fires first?" — then open the real code together and
  check.

## Ending the session

Do not end the teaching loop until every checklist item is verified or explicitly
skipped by the human — treat this as the goal state. When everything is checked,
close with: the final checklist, the three things most worth remembering, and the
follow-ups the human now owns.