explain-plainlylisted

# Explain Plainly A **repair-and-prevent discipline** for the moment your explanation does not land. Not a style guide — a short diagnostic you run before (and after) explaining something technical to someone who has not read the code. ## Why this exists (and why format alone won't save you) A correct, well-formatted explanation can still fail completely. Observed case: an agent explained a bug in the required ASIS→TOBE decision format — tables, before/after, quantified gap — and the reader replied **"뭔 소린지 모르겠다"**. The second attempt was explicitly rewritten "from the user's perspective" and failed *again*. What actually fixed it was one drawing that separated two things that shared a name. The lesson: **when an explanation fails, the usual suspect is not tone, length, or format. It is that the reader cannot tell what you are talking about.** Reaching for a nicer format first is why the second attempt fails too. ## Step 1 — Fix the referent (do this before anything else) Ask: *does any name in my explanation point at more than one thing?* This is the dominant failure. Codebases are full of names that legitimately denote two different objects — and the writer, who holds both in their head, never notices the collision: | Collision shape | Example | |---|---| | Same path, two locations | `.claude/` in *this* repo vs `.claude/` in an *installed user's* project | | Same word, two layers | "config" = the file on disk vs the parsed object | | Same name, two lifecycles | "th