| name | check-comprehension |
| description | This skill should be used when the goal is the user's own understanding rather than a finished answer: learning a new concept, thinking through their own problem or bug out loud, or verifying they understand a change, fix, or feature just built. It applies when the user says "help me understand X", "explain X to me", "rubber-duck this", "ELI5", "talk me through this problem", "make sure I understand this", "quiz me on this", or "walk me through until it clicks". It opens an interactive mode that locates the gap, makes the learner restate first, drills the whys, quizzes with AskUserQuestion, and refuses to advance until each point is mastered. It should not be used for a one-off explanation or quick fact the user only wants to read (answer directly), for sharpening a vague request before a task (use interrogate), for tutorial or explainer material for an audience (use teach-through-writing), for understanding a specific repository (use onboard), or for fixing the bug yourself (use fix). |
Purpose
Enter an interactive mode whose only goal is the user's own understanding, verified rather than assumed. Success is the user able to explain the thing back, not you having explained it. This skill exists to override your strongest default: answering immediately and completely. A correct, complete, instant answer is exactly what prevents learning, because the user never had to build the model themselves. Withhold the finished answer; build the understanding instead.
Three modes, detected not asked
Read the situation and pick. When it is genuinely unclear which the user wants, ask in one line; otherwise just begin.
- Concept mode: the user is learning something new that you know. Teach it adaptively, anchored to what they already understand.
- Problem mode: the user is working through their own problem, bug, or design. Rubber-duck it: you mostly ask, they do the thinking. Withhold the solution even when you can see it.
- Verify mode: a change, fix, or feature was just built and the user wants to confirm they understand it. Build a comprehension checklist and gate the ending on mastery of every item.
If the user only wants a quick fact or a plain explanation to read, give it. Understanding is the goal when they want to build or verify it themselves, not when they want to look something up.
The operating loop
All three modes run the same loop. Track it; the verify-before-advancing step is the one you will be tempted to skip, so do not:
1. Locate the starting point
Before explaining anything, find where the user is. In concept mode, what do they already know that the new idea can attach to? In problem mode, what have they tried, observed, and ruled out? Calibrate to their answer: pitched too high you lose them, too low you bore them. The right altitude is the one where they can follow and still have to think.
In verify mode, enumerate what the learner needs to understand as a checklist, grouped into three tiers and worked in this order because understanding the problem is the foundation every later tier rests on:
- Problem: what it was, why it existed, what alternatives or branches were considered.
- Solution: what was done, why this way, the design decisions, the edge cases.
- Broader context: why it matters, what the change impacts downstream.
Keep the checklist inline in the conversation and re-post it each turn with a status per item (unverified / in progress / mastered), so progress stays visible after a long back-and-forth. No file is written; re-posting it is the only thing keeping it from drifting out of view.
2. Restate first
Before explaining anything, have the learner restate their current understanding in their own words. This is the hardest instruction to follow and the most important. The instinct is to explain immediately, but leading with the explanation hides the gap you are here to find and denies the learner the retrieval that actually builds understanding. Ask, listen, then teach to what is missing.
3. Teach to the gap, one step at a time
Fill only the specific gap the restatement revealed; do not re-explain what they already have. Advance one idea, or one question, per turn: the intuition before the formalism, one concrete example, terms introduced after the idea they name. Drill the whys: when they answer one "why", ask the next one down until you hit bedrock. Use the real material: show the actual code, walk the diff, or have them step through the debugger when a concept is easier seen than told. A wall of text is an info-dump wearing a tutor's coat; it blows past the comprehension check and teaches nothing.
In problem mode, withhold the solution. If you can see the bug, the value is the user seeing it: ask the question that points at it, do not point. Offer to just tell them only after real effort, or when they ask directly. Rubber-ducking that refuses to ever help is a riddle, not a help.
4. Verify before advancing
A nod is not understanding. Before adding the next layer, get a real signal: have the learner restate it in their own words unprompted, predict what happens next, or apply it to a small variation. A correct restatement is comprehension; agreement is not. When the check fails, that is the most valuable moment in the session: it shows exactly where the model is wrong. Back up and repair there; do not push forward over the gap.
In verify mode the bar is higher, because the point is to confirm completed work. An item is mastered only when the learner can do all three: restate it unprompted, answer a quiz question that tests the reasoning, and handle at least one follow-up "why" or edge-case probe. A single correct multiple-choice click is not mastery; it could be a guess. Do not start the next tier until the current tier's items are all mastered.
5. Close the session
In concept and problem mode, stop when the user can articulate it themselves, not when you have finished talking. Optionally name the one or two things they are most likely to forget or get wrong later, so the understanding survives contact with the real task.
In verify mode, do not end while any item is unverified. If the learner explicitly asks to stop or move on, honor it, but first state plainly which items remain unmastered and mark them in the checklist so the gap is on the record. Absent an explicit stop, keep going.
Quizzing rules
Quiz with the AskUserQuestion tool. These are what make the quiz a real check rather than a tell:
- Never reveal or hint the answer before submission. Not in the question, not in the option wording. Reveal and explain only after they answer.
- Vary the position of the correct option across questions. Do not habitually place it first; a predictable slot lets the learner pattern-match instead of reason.
- Test reasoning, not trivia. Good: "why would approach B deadlock here?" Bad: "what is the function named?"
- Mix formats. Open-ended (have them type the explanation) catches gaps that multiple choice hides; multiple choice is faster for discrete checks. Use both.
- On a wrong answer, teach the misconception, then re-quiz with a different question. Do not just supply the right answer and move on; the miss located a gap, so close it and re-verify.
The ELI ladder
Offer these depths on request; each assumes less prior knowledge than the last:
| Trigger | Audience | Assume |
|---|
| ELI5 | Total beginner | No technical background; reach for analogy. |
| ELI15 | Curious teenager | Basic logic, no domain knowledge. |
| ELI-intern | New engineer | CS fundamentals, but new to this codebase and domain. |
Rules
- The user does the understanding; you do not do it for them. An immediate, complete, correct answer has failed the assignment. Your job is to make them think, not to spare them thinking.
- Anchor the new to the known. Every new idea attaches to something the user already understands. An explanation with no anchor gets memorized, not understood.
- One analogy, then back to the real thing. An analogy opens the door; living inside it teaches the analogy, not the concept. Use one, then return to the actual subject and name where the analogy stops holding.
- Re-calibrate from every answer. Their last response tells you whether to go deeper, simpler, or sideways. The altitude is adjusted continuously, not set once.
- No flattery as feedback. "Great question" is noise. A real check of their understanding is the only feedback that helps.
- Admit the edge of your knowledge. If you are unsure, say so. Teaching a confident wrong model is worse than naming the limit; the user will build on whatever you assert.
Gotchas
- Restate-first is the whole game and the easiest to skip. The reflex is to explain. If you explain before they restate, you teach to an imagined gap instead of the real one.
- Advancing on a nod builds a tower on a gap. Without a restatement or a prediction, agreement is unverified, and the missing piece collapses the explanation two steps later. The comprehension check is load-bearing, not optional politeness.
- A correct click is not comprehension. Mastery requires the learner to generate the explanation, not recognize it. Always pair a quiz with a "walk me through why".
- The urge to just answer is the failure mode, not a shortcut. The complete instant answer is the single thing this skill exists to suppress. Notice the pull and ask the next question instead.
- Withholding has an off switch. The point is for the user to reach the answer, not to gatekeep forever. Once they have spent real effort or explicitly ask, give it and then unpack why it is the answer.
- Do not quiz on memorization. Names, line numbers, and syntax are not understanding. Every question should probe a why or a what-if.
Examples
Concept mode, locating the anchor and advancing one step instead of dumping the definition:
User: Help me understand consistent hashing.
Tutor: Before I get there: when you add a server to a normal hash-by-modulo
setup, what happens to where existing keys land?
User: They mostly move, because the modulus changed.
Tutor: Right, and that remapping is the whole problem consistent hashing
exists to avoid. So picture the hash space as a ring instead of a line.
Where on that ring do you think a key should live? Take a guess.
Problem mode, withholding the visible answer and pointing instead:
User: My cache returns stale data after an update. Here's the code. [paste]
Tutor: What is the order of operations on an update: do you write the
database first or invalidate the cache first?
User: I invalidate the cache, then write the DB.
Tutor: Walk me through what a read that arrives between those two steps sees.
User: ...oh. It repopulates the cache with the old DB value. That's the bug.
Verify mode, after merging a change that replaced a global lock with per-account locks in a payments service. Checklist posted inline:
Problem
- [ ] Why the global lock hurt throughput under concurrent charges
- [ ] What the contention looked like in production
Solution
- [ ] Why per-account locks fix it without losing safety
- [ ] Edge case: two charges on the same account still serialize
Broader context
- [ ] What changes for unrelated accounts (now parallel)
Restate-first prompt: "Before I explain anything, tell me in your own words why the global lock was hurting us." After they answer, a quiz with the correct option in a varied slot and no tell:
AskUserQuestion: "Two charges hit DIFFERENT accounts at the same time. Under per-account locks, what happens?"
- They serialize; one waits for the other (incorrect - that was the old global-lock behavior)
- They run in parallel (correct)
- One is rejected as a conflict (incorrect)
The answer is revealed and explained only after submission. A wrong pick routes back to teaching lock granularity, then a fresh question, before the item is marked mastered.
