Plain-Language Plan Explanation
pdd:explain turns a plan into one explanation a non-engineer can act on: what each requirement
is for, what each design decision bought and cost, and what each check catches. The plan here is the
PRD.md that pdd:plan produced together with the task list that pdd:decompose produced. The
explanation is a deliverable in its own right, and it works as a test instrument: a plan that resists
explanation without jargon usually rests on an assumption nobody stated.
The explanation is written in the reader's language. The section labels, entry labels and terminology
below are therefore the labels in their English form; assets/EXPLAIN.md carries the authoritative set and
they must be rendered in the reader's language when that is not English. Whatever the language, the label
set is a contract: the same five parts per requirement, in the same order, so a reader can compare entries
and find a missing one.
When to use
- The user asks what a plan, PRD or task list actually does, or asks for a version a non-engineer, client, partner or investor can read ("explain it with a metaphor", "no technical terms", "for a non-technical reader").
- The owner wants to approve or challenge a plan before implementation money is spent.
- A change must be explained to someone who will never open the repo.
- Routing:
pdd:planwrites and revises the plan,pdd:decomposesplits it,pdd:implementimplements it, andpdd:reviewjudges code quality. This skill explains the plan and leaves the verdict to the owner.
Preconditions
- Read three things in full before writing a sentence:
<plan-dir>/PRD.md,<plan-dir>/TASKS.md, and every<plan-dir>/tasks/T<NN>-*.md. Reading a summary in place of those originals is the usual cause of an explanation that silently drops a requirement. - The output is
<plan-dir>/EXPLAIN.md, built fromassets/EXPLAIN.md. - Language: the reader's language, which may differ from the plan's. Identifiers used as labels
(
REQ-…,D1,F1, file names) stay untranslated; technical vocabulary in prose is banned outright — seereferences/plain-language-lexicon.md. - The plan is read-only:
PRD.md,TASKS.mdandtasks/stay untouched. A contradiction found while explaining goes intoEXPLAIN.mdand into the reply to the user, and the plan itself keeps its text.
Workflow
Inventory with code rather than by eye. Enumerate every
REQ-*id, everyD<n>decision, every flow, every state, invariant and refusal class in the domain model, and every task id. Write the inventory to a scratch file and print the counts. Those counts become the completeness gate at step 9, because a 40-requirement plan read by eye loses three and the reader cannot tell.Choose one metaphor domain for the whole document. Criteria: the domain belongs to the reader's world (customs, a bank counter, a warehouse, a kitchen, a post office, property management, a water utility); it has room for permissions, refusals, queues, caps, duplicates, ordering and bookkeeping; and it is not software wearing a costume (a filing cabinet, "the cloud", an assembly line in the data-pipeline sense all read as plain language while explaining nothing). Write the domain down together with where it stops working, before using it.
Build the role table before prose. Each actor, each stored thing, each permission and each record of what happened gets one row: role in the metaphor / thing in the plan / id. An entity without an honest role stays unmapped and is explained in plain prose; an invented role makes the metaphor lie.
Explain the requirements, one section per
REQ, ordered by the reader's journey (what happens first, in time), with the id as a label only. Two kinds take two shapes: a functionalREQ-Fcarries scene / guarantee / what happens without it / boundary / evidence; an architecturalREQ-Acarries the rule / where it is violated today / what the check does / what a breach looks like. An architectural requirement explained through a user scene is a fiction: nobody meets a dependency direction. Each entry carries five parts, one sentence each:- scene — one specific person at one specific moment meets something;
- guarantee — what the system then guarantees, with every stated number and its unit kept intact;
- if this guarantee were absent — the concrete failure as an event (who discovers it, when, and what is lost), stated in the language of losses rather than of risk;
- boundary cases — which of empty / full / the same thing sent twice / reversed order / malformed data / broken off halfway apply here, in plain words;
- visible evidence — where a bystander confirms the guarantee held.
The optional "in the metaphor" line makes a sixth, and it is deleted wherever it translates back to nothing.
Explain each decision as a fork rather than as an obvious right answer: two roads → which one was taken → how the other one breaks in a specific incident (not "it is worse") → the cost of this one (no choice is free) → under what condition it should be overturned. The cost line and the reversal condition are mandatory; a decision section that lists benefits alone argues for the decision rather than explaining it.
Explain the verification, one section per flow. Each flow's checks answer three questions: which mistake it prevents — the plausible wrong build, drawn from the flow's refusal classes and invariants; where it is visible — the surface a bystander would look at; what it cannot catch — the class of mistake this check lets through, marked "(inference)" where you derived it rather than read it. A flow with no model yet carries not yet verified: the checks are planned, so the owner knows which guarantees are described rather than demonstrated.
Pressure-test the metaphor (see
references/analogy-engineering.md). Push it until it breaks, then either repair the mapping or write that passage in plain prose and record the limit in §6. The metaphor never overrides the document.Record what the document leaves unstated. §7 lists each silence as a question the owner must answer, with the
REQit would change. §8 lists requirements that cannot both hold, quoted from both sides, and leaves the choice with the owner.Deliver. Write
EXPLAIN.md, walk the checklist below against your own text, then reply with the one-paragraph version, the two or three things that actually need the owner's decision, and the file attached.
Decision rules
Jargon
- A word is jargon when an intelligent reader from outside software would have to ask about it. The
test is the reader, not the dictionary.
references/plain-language-lexicon.mdcarries the banlist and the substitutions: a new term enters the ban by adding a row to §2 of that file. - Renaming a term in plainer words still leaves it a term.
schema→ "schema is what a table looks like" still fails. Write "which columns this table has and what goes in each". - Numbers serve clarity rather than jargon. Concrete figures beat vague ones — "100 ms", "5 times",
"3 people" over "fast", "a few". Keep every number the requirement froze, with its unit;
`--retries 3`may become "resend at most 3 times". - A quoted original survives once. A file name, a command the user will type or an error line they will see on screen appears in backticks, immediately followed by its plain meaning, because the reader will meet that string and hiding it sets a trap. Everything else is translated. Backticked strings and appendix A are exempt; the ban applies to prose.
- A refusal stays a refusal. "The system handles it automatically" erases the design. Say who is refused, under what condition, and what they see; a refusal the owner cannot picture is a refusal he cannot veto.
Metaphor
- One domain serves the whole document. A second domain gets its own section with its own declared scope, and the two never mix inside a paragraph.
- A metaphor sentence earns its place by translating back to one contract clause or one concrete failure. A sentence that translates back to nothing is decoration and gets cut.
- The text outranks the analogy. Where the two disagree, the text states the requirement and the analogy counts as a defect.
- Vague virtues take an observable difference instead of a metaphor. "Efficient", "robust", "scalable" have no counterpart in any domain; replace each with how long someone waits, how much is lost when it breaks, what happens with twice the people.
Honesty
- Mark your own inference "(inference)". A reason the document never gave belongs to the assistant, and the document keeps its own reasons.
- Explanation states what is required, what it costs and when the choice would be wrong. A verdict, where the user asks for one, is given separately and labelled as the assistant's.
- Attribute only what the user said. Any alternative the assistant proposes is labelled as the assistant's own and stays outside the user's position.
- Completeness beats elegance. Every requirement gets an entry, including the dull ones: a missing entry is a defect the reader cannot detect, while a boring paragraph is a cost the reader can skip.
- An unexplainable requirement is a plan gap rather than a writing problem. A requirement that resists plain language, or that can be explained only by inventing a mechanism, goes into §7 as a question and into the reply — never under a fluent paragraph. A reader must know when prose stands in for a design nobody stated.
- Scale does not license summary. A 40-requirement PRD keeps 40 entries, grouped under an area-level
scene paragraph (one paragraph saying what this batch of people is doing).
Requirements never fold into "other": a missing
REQentry, or an entry with no reading of its own, is a defect the reader cannot detect.
Pitfalls
| Symptom | Cause | Fix |
|---|---|---|
| Reader says "roughly got it" but cannot restate one guarantee | the section is all metaphor and no contract | add the guarantee and evidence lines with their numbers |
| The metaphor grows, the requirements shrink | the metaphor became the subject | one metaphor sentence per contract clause; cut the rest |
| A warehouse and a bank in the same paragraph | two domains | one domain per document, or a separate section with its own scope |
| The explanation reads more complete than the PRD | you supplied reasons nobody wrote | mark "(inference)" or delete |
| Every decision looks obviously right | only benefits were listed | add the cost and the reversal condition to every D |
| The verification section is a test list | nobody said what error it prevents | lead each flow's checks with the plausible wrong build |
| The owner asks "so will it go wrong or not" and there is no answer | blind spots unwritten | add what each check cannot catch |
| The owner approves a check that never ran | the flow is modelled after the code landed and the entry omits "not yet verified" | add that marker to the flow's section |
| Requirements explained in id order | the reader follows ids instead of events | order by the reader's journey; ids stay labels |
| §7 is empty | silences were filled by guesswork | list each silence as a question, with the REQ it would change |
| A requirement explained only through its file name | path used as a substitute for behaviour | say what an outsider observes; the path belongs in the appendix |
Verification
EXPLAIN.mdexists at the declared path and covers everyREQ, everyDand every flow, with the section labels in place, no banlisted term in the body, and per-requirement numbers preserved.- Every
REQ-Fentry carries scene / guarantee / what happens without it / boundary / evidence; everyREQ-Aentry carries the rule / where it is violated today / what the check does / what a breach looks like; every decision entry carries its cost and its reversal condition; every flow's checks carry which mistake they prevent and where they are visible. - Every flow with no model yet carries "not yet verified", and every check the reader is asked to trust names what it cannot catch.
- One metaphor domain serves the document, its limit is stated up front, and §6 records every place it broke.
- The body holds no banlisted term, and every quoted original carries a plain gloss.
- §7 and §8 name the silences and the contradictions, and the owner's decision stays open.
- The chat reply carries the one-paragraph version, the decisions needed, and the file attached.
References
assets/EXPLAIN.md— the document template; every section exists for one item of the checklist.references/analogy-engineering.md— choosing a domain, the role table, the six pressure tests.references/plain-language-lexicon.md— banned terms with substitutions, plain translations of the boundary-case taxonomy, banned sentence shapes. Its §2 is the banlist.- No document-verification script exists, and none is added: coverage and jargon are read by the writer against the checklist, because a script can see a missing id but not a sentence that explains nothing.