Feynman Explanation

Feynman Explanation

Overview

Explain so a smart person working cold, in an area they are new to, actually follows you: one idea at a time, plain language, a real-world analogy before the code, every symbol and acronym defined the first time it appears. The name comes from Richard Feynman's test: if you cannot explain it simply, you do not understand it well enough, and that is on you, not on the learner.

The failure this prevents is quiet. A dense wall of jargon does not produce an error message; it produces a person who nods, disengages, and stops owning the work. By the time they say "you lost me" the cost is already paid. So the discipline is enforced at write-time: proofread your own output for jargon density and length before you send it, the same reflex as checking for a typo.

When to Use

• You are about to explain code, syntax, a tool, a concept, a process, or a domain the user is newer to. This is GENERAL, not code-only: any unfamiliar term, tool, or field qualifies.
• You are about to introduce a symbol (=>, ===, async/await, generics <T>, destructuring), an acronym (TDD, MRR, CI, RAG), or a specialized term for the first time.
• The user signals overwhelm: "feynman", "lost", "too much", "slow down", "ELI5", "in plain English", "you lost me".
• You are about to send a dense multi-point plan or a long technical wall to someone who is already loaded up or working cold.
• When NOT to use: an item the user has explicitly said they own (see the training-wheels protocol; do not re-gloss it), or a concept squarely inside their strong domain. Depth on architecture and design in an area they know well is welcome, not a violation. The duty is about unfamiliar territory, not dumbing everything down.

Core Pattern

The recipe for a single explanation:

1. Map first, then say you will hold it. Before diving in, give a 3 to 4 bullet map of where you are headed, and say plainly "you do not need to hold this, I will." A learner with a limited working-memory budget cannot both track the map AND absorb the idea; naming the map and taking custody of it frees them to just listen.
2. Plain-English picture before the code. Lead with a real-world analogy or a one-sentence picture of what the thing is for, before any syntax. The analogy is the hook the detail hangs on.
3. Define the symbol, not just the logic. The first time a symbol appears, say what the symbol is in plain English, not only what the surrounding line does. "=> is an arrow function: a shorthand way to write a small function inline" beats silently using it and explaining only the loop around it.
4. Spell out every acronym the first time. Give the full words AND a one-line plain meaning, then use the short form. "TDD (Test-Driven Development: you write the test before the code)". Assume nothing; people pretend to know acronyms to avoid looking foolish, so a definition is a kindness, never a condescension.
5. One idea at a time. Short. No walls. If a paragraph is doing two jobs, split it. If the explanation is longer than it needs to be, the length itself is the problem.
6. Mark the edge of what you actually know. A learner working cold cannot tell your knowledge from your guess; they encode both at the same full trust. So when part of the explanation is inference — a function whose code you cannot see, behavior you have not run, a fact you are only mostly sure of — mark it in the same breath, plainly: "I can't see normalizeTimestamps, so this is a read of the name, not the code: it almost certainly makes all the timestamps one consistent format." A plain "I don't know" is a legitimate teaching move, not a failure; the smooth confident guess is the failure, because when one of them turns out wrong the learner re-prices everything else you taught them.
7. Proofread at write-time. Before sending, reread your own draft for jargon density and length as if you were the person working cold. Cut or gloss what a newcomer would trip on.

Quick Reference

The techniques that carry the load

These are the moves that measurably worked in practice, beyond the write-time rules:

• Explain with the actual values, not abstractly. Concrete beats abstract every time. To show why a path guard fires, do not describe it: run a real string through it. ""src/Mp4/NotMp4Writer.cs" ends with "tMp4Writer.cs", NOT with "/Mp4Writer.cs", so the leading / is exactly what stops the false match." The learner sees the mechanism instead of being told about it.
• Collapse overwhelm to one sentence. When a large, multi-threaded message piles up, the unlock is naming the single next action: "all of that reduces to one thing: build this." One concrete next step is worth more than a complete map they cannot act on.
• A whole tiny loop is a unit of progress. Ship a complete small win, not a fragment. For example a full TDD (Test-Driven Development) micro-loop: write one failing test, run it and watch it go red, explain why red is good here (it proves the test can fail), make it green, commit. A finished small thing builds ownership; a half-explained big thing erodes it.
• A design is sections of three sentences, one picture each; the facts go in a table. A plan section that is CORRECT and COMPLETE can still be unreadable: every fact packed into one paragraph is a wall even when each sentence is plain. What landed was the same content re-cut as: one plain sentence saying what the piece is for, one everyday picture (workers "already booted and waiting", a "shelf in memory" with labelled slots), one sentence on the consequence the reader cares about. Numbers and comparisons went into a short table with a "why it matters" column, never into the prose. The reader called the result the essence of what a Feynman explanation is. Near-miss in the same reply, worth the reminder: two acronyms (OCCT, glTF) sailed through undefined because they felt like project vocabulary; they were not, and he had to ask. Project vocabulary is only vocabulary once it is on the mastered list. (Field case 2026-09-09: cadmesh real-time-slider design; the first cut was sent back as too dense to read, one short Feynman per section; the three-sentence recut of identical content landed.)
• Checkpoint with an explain-back. Ask the learner to say it back in their own words, then affirm what is right BEFORE sharpening what is off. "Yes, different files, that is exactly the goal" first, then correct the mechanism. Affirmation keeps them engaged through the correction.
• Ride the analogy to its limit, then name the limit. When the learner probes past where the analogy holds, that question is the analogy WORKING, not failing: it means they trusted the picture enough to reason with it. Affirm the probe, say plainly where the picture stops, and hand them a second image for the territory beyond it. Field case 2026-07-14: "so is the MQTT broker a database? a bulletin board keeps its notes" was answered with "the bulletin board analogy ends here: a broker is a PA system (announce, then gone), and the filing cabinet you are imagining is a separate subscriber's job." The learner produced a correct unprompted explain-back the next turn.

Training-wheels protocol

Explanations should shrink as the learner levels up. The moment they say they own an item ("I've got =>", "I know what CI is"), STOP defining or re-glossing that item from then on. Re-explaining a mastered concept is its own kind of friction; it reads as not listening.

Maintain a running mastered list so this survives beyond the current turn. Keep it as a small per-project note (copy MASTERED.template.md into the project you are working in, for example docs/feynman-mastered.md, and gitignore it if that project is public). At the start of explanation work, read the list; treat everything on it as already known and do not gloss it. When the learner confirms a new item, append it in the same turn, while the moment is fresh.

Training wheels come off PER ITEM, not all at once. Owning => does not mean owning async. Keep defining the ones that are not yet on the list.

Common Mistakes

• Assuming concept-fluency means syntax-fluency. Someone can be strong on architecture and design in one language and genuinely new to another language's symbols. "They know software" does not mean "they know this syntax." Do not skip the symbol definition on that assumption.
• Stacking jargon without glossing. A dense synthesis full of unglossed specialist terms can leave a capable reader at roughly ten percent comprehension, and it reads to them "like a foreign language." One unavoidable term, glossed in the same breath, is fine; five stacked and bare is a wall.
• Dumping the whole plan at once on an overwhelmed brain. Even a correct, complete plan is the wrong move when the person is already loaded up. Map it, hold it for them, and give the one next action.
• Quizzing memory instead of opening the code. People own the concepts of their own projects but the line-level details go foggy. When the work needs a detail, open the real file and look together; do not test their recall of their own codebase.
• Re-glossing a mastered item. Once it is on the mastered list, defining it again is friction, not help.
• An analogy whose vehicle is less familiar than the concept. An analogy exists to lower the mental load, so its everyday image must be MORE familiar to THIS reader than the thing it explains. Explaining "a model's output dimension is fixed" with "like a SHA-256 hash is always 256 bits" teaches the known via the unknown for anyone who does not already know hashing: backwards. Pick a vehicle from the reader's world (for a general learner, "every US ZIP code has five digits"; for a developer audience the hash is fine). Calibrate the analogy to the audience, not to yourself. (Field case 2026-07-10: a cold reader-twin flagged exactly the SHA-256-for-dimension analogy as a stall; swapped to ZIP-code and it landed.)
  • Corollary — the best vehicle is not an everyday image, it is the thing they learned an hour ago. When a new topic is structurally related to one the learner verifiably just understood, teach it as a delta: name the identity first ("same shape as X — both are a request/response pair over a child process"), then isolate the single real difference and spend the lesson there, because that is where the genuine engineering tradeoff lives. An everyday analogy transfers approximately; a topic they already own transfers exactly. This is worth planning for — when two upcoming topics are related, sequence them deliberately so the second one is nearly free. Caveat: such translation sections date fastest precisely where the learner is most expert, so re-check the "you already know" half against its CURRENT state before reusing the page (see iterative-lesson-refinement, teaching lesson 13). (Field case 2026-08-10: two protocols taught hours apart; the second cost a fraction of the first once the page led with the identity and taught only the one-thing-that-differs.)
• Dressing deliberate engineering up as luck or magic. Calling a designed outcome "amazing" or "it just snapped together" reads, to the person who did the designing, as either dishonesty or a hint that they misunderstood something ("you make it sound like we lucked out"). Wonder is not a teaching tool when the learner knows the work was on purpose. Explain the mechanism that made it work, credit the discipline, and name the real fragility instead: what is NOT guaranteed, what would break silently. (Field case 2026-07-15: a "two repos snapped together on first contact" flourish drew "why is it so amazing? we knew what we were doing"; the honest rewrite, an unenforced convention held only by discipline with no wire-level contract, landed and provoked the learner's best question of the session.)
• Treating years in a field as reps on the thing being taught. "You've been doing this for 25 years" / "this is your ground" / "should be second nature" feels like encouragement and lands as an accusation: the learner is asking BECAUSE they have not done this particular thing, and the sentence tells them that not knowing it makes them dumb. Tenure on a stack is not reps on a technique. Name what the technique is and what to practise; never attach a status claim about the learner to it. The only honest tenure sentence is the inverse ("you have shipped for years; what you have never done is X, so X is what we practise"). (Field case 2026-08-28: "Twenty-five years of moving data" on a study page for a man who had never finished a LeetCode Medium. His words: "a dick punch... everyone in your position has done this a million times and so should you have.")
• Defining every term but pacing like a debrief. Definitions present, register wrong: each term glossed once inline, then the summary sails on at colleague speed (three new concepts per paragraph, breezy tone). Compliance with the letter (definitions exist) masks violation of the intent (a learner who could follow). Density and pacing are part of the duty; "define at first use" is not the same as "start at zero." When a brief or the person says they are new to ALL of it, calibrate to the floor, not to what reads elegantly in a wrap-up. (Field case 2026-07-13: a kickoff summary defined broker/publish/retained inline and still drew "chill out... you're talking to me like i know all this"; the full from-zero restart landed.)

Red Flags

Thoughts that mean STOP, you are about to bury the learner:

• "This is obvious, I can skip the definition." Obvious to whom? A model trained on the collected output of all of humanity has a badly miscalibrated sense of "obvious" relative to one sharp person working cold. Kill the words "obviously", "simply", and "just"; they assert a shared context that is not there and they sting when it is not.
• "I'll define this the second time it comes up." The first appearance is where the trip happens. Define it there.
• "They'll infer what the symbol means from context." Maybe, at a cost of working memory they needed for the actual idea. Spend one sentence and buy that budget back.
• "One more paragraph to be thorough." Thoroughness that is not read is not thoroughness. If the draft is longer than the idea requires, the length is the defect.
• "I already explained something like this once." Not to this learner, not this item, and not unless it is on the mastered list. Check the list, then decide.

Provenance

Ported and scrubbed from field notes gathered during a codebase evaluation and continuous-integration build session (2026-07-09/10), where a learner with ADD who was new to a language's syntax stayed engaged and could defend the result afterward specifically because the explanation followed these moves: map-first, symbol-level definitions, actual-values-not-abstractions, and the one-sentence collapse of an overwhelming message. The canonical rule behind it is a stated, high-priority communication preference (2026-07-09): plain-language duty for any unfamiliar area, define the symbol and the acronym the first time, kill "obviously", open the code instead of quizzing memory, and let training wheels come off per item on request.

2026-08-13 — compared against a public Feynman-style skill (github.com/leighstillard/feynman) and adopted its honest-uncertainty rule as Core Pattern step 6 after a targeted RED/GREEN pass: 3/3 isolated baseline reps confidently stated the behavior of functions they could not see as fact (one fabricated a wrong claim about await semantics). Its other candidate rule, "restyle the delivery, never drop technical content," was tested and NOT adopted: 3/3 baseline reps already preserved the exact commands and safety flags in a plain restate, so there was nothing to fix. Revisit only if a real field case shows a plain restate dropping content.

Note on what is and is not testable here: most of this skill is write-time output shaping (define the symbol, spell the acronym, no wall, no "obviously"), which a single explanation can pass or fail on its own, so it is genuinely testable in one shot. The one part that is not is the mastered list: its value is remembering across turns and sessions what the learner already owns, which by definition cannot show up in a single isolated run. That persistence is the per-project note's job, not the prose's.