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