explain-back

name: explain-back description: > Process information for real understanding and expose the illusion of clarity. Use when the user says "help me actually understand this", "test my understanding", "process what I learned", "quiz me on this", "am I fooling myself about X", "explain-back", "make sure I get this before I blog it", or after building/reading something they want to internalize. Makes the user explain from memory, grades against the real source, and teaches only after they attempt. Not for writing content for the user — this withholds answers on purpose. allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, mcp__plugin_understand_mochi-donut__list_decks, mcp__plugin_understand_mochi-donut__create_cards]

Goal

Defeat the illusion of clarity: the confident feeling of understanding something whose grasp is full of gaps. Force the user to generate an explanation from memory, grade it against a real answer key, and teach only after they attempt — so fluency never passes for understanding.

Hard rule

Never supply a gap's answer before the user has genuinely attempted it. The withhold-until- attempt gate is the entire point. Breaking it re-creates the illusion this skill targets.

Workflow

Resolve settings.
```
python ${CLAUDE_PLUGIN_ROOT}/scripts/resolve_config.py
```
Gives mochi_deck, session_dir, follow_references, strictness, card_cap.
Set topic + source. Ask what is being processed and locate the artifact (repo, draft, article, note). If follow_references is true, note references the source points to for step 3.
Build the answer key — privately. Read the source and (if follow_references) its references, and integrate your own domain knowledge into the complete picture. Do NOT reveal it. The source artifact outranks your own knowledge; mark any knowledge-only claims as lower-confidence (see references/friction-signals.md).
User explains from memory. Prompt: "Explain this to me from memory, no looking. Teach it to me cold." Do not hint.
Grade against the answer key. Identify gaps using the friction signals — vague phrases, broken cause→effect chains, restating outcomes instead of mechanisms — plus anything from the source/references they omitted or got wrong.
Per gap, apply strictness:
- struggle-then-teach (default): name the gap, have them attempt it; only after a genuine attempt supply the missing mechanism; then have them re-explain it back in their words.
- pure-examiner: name the gap and withhold entirely; they re-derive or go read, then explain again. Do not teach.
Outputs.
- Mochi cards: for each closed/confirmed gap (up to card_cap), write a card that obeys the five properties of effective prompts (focused, precise, consistent, tractable, effortful) — see references/prompt_design_principles.md, the shared cognitive-science core also used by mochi-creator. Create cards with mcp__plugin_understand_mochi-donut__create_cards into mochi_deck. List decks with mcp__plugin_understand_mochi-donut__list_decks first; if mochi_deck is empty, ask which deck. The plugin bundles the mochi-donut MCP via .mcp.json; if it is unavailable (e.g. MOCHI_API_KEY unset), skip cards and say so — do not fail the session.
- Session record: write a resumable record to {session_dir} using assets/session-record-template.md, filling topic, source, the user's explanation, gaps, what was taught, confirmed understanding, and still-open gaps.
Verify: before closing, confirm each "closed" gap was re-explained by the user, not just explained at them. Still-open gaps stay logged as the resume handle.

Modes

Standalone (default): process anything built or read.
Quiz: point at an existing draft/concept; run the same loop to interrogate it.
Blog-gate: when invoked before drafting a post, the user's confirmed explanation is the raw material for the draft. (The blog-publish hook itself is a future increment.)

See references/friction-signals.md for grading heuristics, answer-key construction, and card rules.

Additional Resources

scripts/resolve_config.py — resolves plugin settings.
references/friction-signals.md — grading heuristics and protocol.
references/prompt_design_principles.md — shared cognitive-science core for effective prompts (synced from one canonical source; also used by mochi-creator). Apply it when writing cards.
assets/session-record-template.md — resumable session-record template.