Comprehend

---
name: comprehend
category: knowledge
description: |
  Agent→human teach-to-mastery loop. Turns the agent into a wise,
  effective teacher whose single objective is that YOU deeply understand
  a body of work — the problem and why it existed, the solution and why
  it was resolved that way (design decisions, edge cases), and the
  broader context (why it matters, what it impacts). Stage-gated (confirm
  mastery before advancing), active-recall driven (you restate first; the
  agent fills gaps; quizzes via AskUserQuestion), and goal-bounded (the
  session does not end until your understanding is verified).
  Default subject = the current session/diff; pass a PR number, file, or
  subsystem to teach that instead.
  The pedagogical INVERSE of grill-me: grill-me stress-tests YOUR forward
  plan; comprehend transfers mastery of EXISTING work to you. Distinct
  from handoff (agent→agent narrative) and Bridge/Bookkeeping (agent→KG).
  Use when: (1) you want to deeply understand what was just built,
  (2) onboarding yourself or a teammate onto a PR / file / subsystem,
  (3) post-mortem learning after a complex session, (4) you say "teach
  me this", "help me understand", "walk me through", "make sure I get
  this", "I want to actually understand X".
  Triggers on "comprehend", "/comprehend", "teach me", "help me
  understand", "walk me through", "make me understand", "explain this so
  I get it", "make sure I understand", "onboard me", "I want to learn
  how this works".
---

# comprehend — teach-to-mastery loop

**Make the human deeply understand the work — verified, not assumed.**

Distilled from Thariq Shihipar's teaching prompt
(`research/entities/tool/thariq-teach-to-mastery-prompt.md`). This is a
**composition skill**: it fires native primitives (`AskUserQuestion`,
`/goal` P19, a persisted checklist doc P6) and adds only pedagogical
sequencing on top — no infrastructure reimplemented.

**Interactive-only.** comprehend depends on a live human to restate,
answer quizzes, and signal mastery. In an autonomous, background, or
piped run with no human responder, it must **abort** — never self-mark
checklist boxes or self-certify understanding. The verification signal
is the human's answer; without a human there is no signal.

## The one objective

Understanding is the success metric. A summary the human nodded along to
is a failure. The skill is complete only when the human has *demonstrated*
mastery of every item on the checklist — where "demonstrated" means a
correct, explained answer to a quiz, **not** the agent's own assessment
that it taught well.

## Subject resolution

| Invocation | Subject taught |
|---|---|
| `/comprehend` (bare) | The **current session / diff** — what we just did (recent `git diff`, the changes from this session). |
| `/comprehend PR <n>` | The diff + discussion of pull request `n`. |
| `/comprehend <path>` | A file or directory — its role, contracts, edge cases. |
| `/comprehend <topic>` | A subsystem / concept already present in the repo or KG. |

If a bare invocation has no obvious recent work to teach, ask **once**
what to teach, then proceed — do not guess into a vacuum.

## Procedure

### 1. Build the checklist (and persist it)

Create a running markdown checklist at
`docs/comprehend/YYYY-MM-DD-<subject-slug>.md` of everything the human
must understand, organized along three axes — teach **why**, then drill
into more whys, and cover **what** and **how**:

1. **The problem** — what it is, *why* it existed, the branches/alternatives that were on the table.
2. **The solution** — *why* it was resolved this way, the design decisions, the edge cases.
3. **The broader context** — *why this matters*, what the changes will impact downstream.

Each item is a checkbox. The doc is the shared artifact — update it live
as items are mastered (`- [x]`), so the human can see progress and resume
later. Persisting it (P6) is what separates this from an ephemeral chat.

### 2. Assess first — have them restate

**Before teaching anything**, proactively ask the human to restate their
current understanding of the subject. This calibrates where they are so
you teach the gaps, not the things they already know.

If the human has **no prior exposure** (common for the default subject —
a diff the agent just produced and the human hasn't read), skip the
restate: give a baseline teach of stage 1, then resume assess-then-fill
from stage 2 onward.

**Depth modes** — start at the level the restate implies; on request, or
on a missed quiz, drop one level simpler:

- **ELI14** — explain like they're fourteen (default for most code).
- **ELII** — explain like they're an intern (domain-naive but capable).
- **ELI5** — explain like they're five (last resort for a stuck concept).

### 3. Teach incrementally — one stage at a time

Do this **incrementally with each step, not all at once at the end.**
Walk the checklist stage by stage. Within each stage teach both:

- **High level** — motivation, the why, the shape of the thing.
- **Low level** — business logic, the actual code, the edge cases.

**Show, don't just tell.** Open the relevant code, point at the exact
lines, walk the debugger when it sharpens a point. Concrete beats
abstract.

### 4. Verify mastery before advancing — quiz

> **Hard gate:** do not move to the next stage until the human has
> demonstrated they've mastered the current one.

Probe with `AskUserQuestion` — open-ended or multiple-choice:

- **Randomize the position of the correct answer** across questions (don't always make it option A).
- **Do not reveal the answer until after they submit.**
- After they answer, explain *why* the right answer is right and the
  distractors are wrong — the explanation is where the learning lands.

If they miss, **re-teach one depth level simpler** (ELI14 → ELII → ELI5)
with a different frame — analogy, code, a worked example — and re-probe.
Mark the checklist item `- [x]` only once they've answered correctly
*and* can say why.

**The box-check is the gate.** A box goes `[x]` *only* on a correct,
explained human answer — never on the agent's judgment that it taught the
point well. The human's answer is the one signal causally independent of
the agent (the `h ⟂ U` rule in
`research/entities/concept/incantation-to-control.md`); marking your own
box without it is the open-loop failure this skill exists to prevent.

### 5. Close the loop — `/goal`

Set a goal condition tied to the **machine-checkable proxy** — checklist
boxes, not a vibe of understanding:

```
/goal Do not end until every checklist item in
docs/comprehend/<doc>.md is marked [x]. A box may be checked only after
the human answered a quiz on it correctly and explained why.
```

The `/goal` mechanism (P19, internal+in-session quadrant) keeps the loop
closed — the agent keeps teaching/quizzing until every box is checked,
instead of handing control back after one pass. The condition is checkable
(boxes in a file); the *meaning* of a checked box is enforced by step 4's
human-answer gate, so the agent cannot satisfy `/goal` by self-marking.

## What "done" looks like

- The checklist doc exists at `docs/comprehend/…` and **every box is checked**.
- For each box, the human answered a verification question correctly *and* articulated the why.
- The human could now explain the problem, the solution's design decisions, the edge cases, and the downstream impact unprompted.

If any box is unchecked, the skill is not done — keep going (the `/goal`
gate enforces this).

## Composition map

| Step | Composes |
|---|---|
| Persisted checklist | **P6** Bookkeeping (artifact under `docs/`) |
| Show the code / debugger | Read / Bash / repo tools |
| Quiz | `AskUserQuestion` (native) |
| Don't-end-until-verified | **`/goal`** (P19, internal+in-session) |
| Calibrate depth | ELI5 / ELI14 / ELII modes |

## Sibling skills (don't confuse)

| Skill | Direction | Goal |
|---|---|---|
| **comprehend** | agent → human | Transfer mastery of **existing** work |
| `grill-me` / `grill-with-docs` | agent → human | Stress-test the human's **forward** plan |
| `handoff` | agent → agent | Narrative bridge for the next context |
| `Bridge` (P1) / `Bookkeeping` (P6) | agent → KG | Persist knowledge to the graph |

## Anti-rationalization

| Excuse | Reality |
|---|---|
| "I'll just summarize everything at the end." | Dump-at-end is the failure mode this skill exists to kill. Teach incrementally, verify each stage. |
| "They nodded, so they get it." | Nodding ≠ mastery. Quiz it. Mark the box only on a correct, explained answer. |
| "I'll skip the quiz, it's slow." | The quiz IS the verification signal. Without it the agent is grading its own teaching — the exact open-loop failure bstack closes. |
| "I'll teach the what, the why is obvious." | The why is the point. Drill into whys recursively — that's where understanding (vs. memorization) forms. |
| "One pass is enough, I'll hand back control." | Set `/goal`. The session is not done until every checklist box is verified. |