explain-back

What this skill does

# Explain-Back

## 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

1. **Resolve settings.**

   ```bash
   python ${CLAUDE_PLUGIN_ROOT}/scripts/resolve_config.py
   ```

   Gives `mochi_deck`, `session_dir`, `follow_references`, `strictness`, `card_cap`.

2. **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.

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`).

4. **User explains from memory.** Prompt: "Explain this to me from memory, no looking. Teach it to
   me cold." Do not hint.

5. **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.

6. **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.

7. **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.

8. **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.