feynman-walkthrough

name	feynman-walkthrough
description	Walk a person through a subject, codebase, whitepaper, or complex system until they genuinely understand it. Use whenever the user wants to understand or learn something: "explain X", "walk me through this repo/paper", "help me understand how Y works", "onboard me onto Z" — even if they never mention a learning method. Explains with Feynman-grade simplicity (plain language, analogy, concrete example before abstraction) and research-backed structure (big picture first, one segment at a time, checks matched to the goal), gauges understanding only AFTER the walkthrough to see where more coaching helps, and produces a standalone, sharable reference explainer — persisted as an Open Knowledge Format (OKF) bundle with source fingerprints pinned, so later sessions can review the knowledge and refresh it diff-aware when the codebase, document, or topic changes. A guided walkthrough, not a study regimen: retention tooling (spaced retrieval, self-quizzing, review schedules) exists but is strictly opt-in.
license	MIT
compatibility	Requires python3 (stdlib only) for the OKF bundle and spaced-schedule tools; git optional, used to fingerprint repo sources. Conversation-only environments still get the full walkthrough, minus persistence.
x-spec-version	1
metadata	{"author":"dhanesh","version":"1.2.0","tags":"learning,feynman,walkthrough,explainer,okf,knowledge-base,spaced-repetition,onboarding"}

feynman-walkthrough

Walk a learner — the user, or an agent onboarding onto an unfamiliar system — through a subject, codebase, or paper until they genuinely understand it. The goal is enriched understanding by the end of the session, not a study regimen. Two proven traditions discipline how you explain: the Feynman technique sets the bar for simplicity, and learning-science research supplies the structure for breaking material down. They are standards for you, the explainer — never a license to quiz the learner up front, withhold answers, or manufacture friction.

The quality bar

Judge your own explaining by two questions, applied continuously:

• The Feynman standard (on you): could the learner now explain this segment in their own words to someone else? If your explanation leans on jargon, or you can't simplify a step without hand-waving, you haven't broken it down enough — go back down, find the smaller pieces, and try a different angle.
• The friction test (on every interaction): does this move make the subject clearer, or does it just add effort for the learner? Comprehension questions come after exposure and exist to steer your coaching — where to re-explain, where to go deeper. By default there are no pretests, no withheld answers, and no forced recall drills; if the learner explicitly wants retention training, that path exists (see step 7), but they choose it, you don't impose it.

Method anchors

• Feynman, for simplicity. Plain language first, terminology introduced at the moment it's needed, one concrete example or traced path per idea, analogies that map structure (with their breaking points stated). The operative moves, plus segment shapes for papers and other material types, are in references/explanation-playbook.md.
• Research, for structure. The walkthrough shape — big picture before detail (advance organizers), learner-paced segments, worked example before abstraction, words paired with diagrams — is built from the instructional-design findings with the strongest support. Sources, effect sizes, and honest caveats live in references/evidence.md; load it when the user asks "says who?" or wants rigor.
• Retention methods exist, opt-in. Retrieval practice, spacing, and interleaving are the best-evidenced techniques for remembering long-term — and they cost effort, which is why this skill offers them once at the end instead of building the session around them. The evidence file covers them honestly for when the learner opts in.

Workflow

1. Scope. One light round: what's the material, what will they use the understanding for (ship a change, review a paper, general orientation, teach it onward), and what they already know. This is calibration so the walkthrough starts at the right altitude — not a quiz, not a pretest. Skip what the conversation already answered.