explain-this

name

explain-this

description

Explain any digital artifact — a paper, PDF, article, or codebase — so the person actually understands it, not just skims it. Explanations are shaped by a persistent learner profile, gated by comprehension quizzes, and feed a spaced-repetition review loop. USE WHEN: explain this, explain this paper / PDF / article / codebase, help me understand this, what does this mean, what is this really saying, break this down, review my cards, explain-this review, explain-this interview. NOT FOR: plain summarization when the user only wants a TL;DR, writing new content, reviewing code for defects, explaining a diff or PR (use explain-diff), or quizzing on work just completed (use socratic-tutor).

Explain This

Understanding is the bottleneck, not information. This skill turns any digital artifact into an explanation the user can genuinely absorb — shaped to how they learn, checked by quizzes that prevent false confidence, and retained through spaced-repetition review. The goal is formation, not summarization: who the user becomes by understanding, not just what they can skim.

State contract

All user state lives in EXPLAIN_THIS_HOME (default ~/.explain-this/) — never in this skill's install directory, so it survives skill updates and is shared across agent hosts:

~/.explain-this/
  LEARNER.md            # who this person is as a learner — read before EVERY explanation
  memory/cards.jsonl    # spaced-repetition cards + SM-2 scheduling state
  memory/signals.jsonl  # append-only quiz-attempt evidence

First run

If ~/.explain-this/LEARNER.md does not exist, do NOT explain anything yet. Run the interview in references/interview.md (~10 minutes), draft LEARNER.md from references/learner-template.md, show it to the user, and apply their corrections. The profile is the product's first artifact.

Every explanation follows the spine

Read LEARNER.md first, then build the explanation in this order:

1. Why does this exist? — the problem the artifact answers. Context before content.
2. The one idea — the single sentence worth retaining above all others.
3. How it works — intuition before mechanism, prose-ordered (literate sequencing), analogies drawn from the learner's deep domains, skipping what their profile says they already know.
4. What can you now do — point at the learner's formation goals: what can they build, argue, or decide that they couldn't before.
5. Check yourself — the quiz. Generate per references/quiz.md; add each question to the card deck per references/review.md.

Depth dial

Default comes from LEARNER.md frontmatter; per-request override phrases win:

Depth	Meaning	Trigger phrases
orient	5-minute orientation	"just orient me", "quick pass"
working	can explain it to a colleague (default)	—
rederivable	could re-derive / re-build it	"really grok", "go deep"

Artifact adapters

Pick the adapter for the artifact type; it defines ingestion and what "meaning" means for that type:

• Papers / PDFs → references/adapters/paper.md
• Articles / markdown / essays → references/adapters/article.md
• Code, diffs, repos → references/adapters/code.md

Output destinations

Markdown is canonical. The user directs the destination ("put it in Obsidian", "give me an HTML file", "just tell me here"); the default lives in LEARNER.md frontmatter. In document output, embed quiz questions at section ends with answers in <details> blocks. An HTML render is an optional layer for interactive quiz widgets — never required.

Review mode

"quiz me" / "review my cards" / "explain-this review" → run the conversational review loop in references/review.md (due cards via scripts/sm2.ts due). When invoked for a NEW explanation while cards are due, mention it once ("6 cards due — review first, or after?") but never block.

Gotchas

• Never skip the profile read. An explanation not shaped by LEARNER.md is a generic summary — the exact thing this skill exists to avoid.
• A summary is not an explanation. If the output could have been produced without the artifact's actual content or without the profile, start over.
• Never write LEARNER.md's Known Weak Patterns from a single session. Only the evidence loop (references/review.md, thresholds) may add entries, and every entry must cite its evidence. One bad quiz is noise, not identity.
• Quiz questions come from the artifact, not the explanation — otherwise they're echo questions that test short-term verbal memory. See references/quiz.md two-pass procedure.
• Grade the user's free-text answers yourself (hit/partial/miss). Never ask them to self-grade; self-grading is generous and corrupts the evidence.
• You wrote the explanation AND grade the quiz — watch for grading inflation. Grade against the artifact and the stored answer/rubric, not against your own explanation's wording. When unsure between hit and partial, choose partial.
• State is sacred. Never reset, rewrite, or prune ~/.explain-this/ except through the documented flows. Losing a learner's history is the worst failure this tool can have.