| 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:
- The problem — what it is, why it existed, the branches/alternatives that were on the table.
- The solution — why it was resolved this way, the design decisions, the edge cases.
- 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. |
