Agent-written 'explain why' docs: pair a writer with an independent reviewer that traces every stated reason to a record
Goal: release docs that explain WHY the design is the way it is (5-whys style), with technical density increasing down the page, rather than restating code.
Setup that worked: two agents. The writer produces git-diff patches only, against the release head, scoped to docs/README/informative spec parts, each with a rationale header. The reviewer reads each doc cold and returns APPROVE/REVISE with line numbers, covering: (1) every design choice and whether its reason is stated AND traceable to a decision record or spec goal; (2) the density curve (audience, problem, mental model, usage, internals); (3) 'what-not-why' sentences to cut; (4) undefined terms and internal nicknames; (5) hard rule violations, which are automatic REVISE.
What the reviewer caught on the first patch: an invented cause for a measured cost (no record supported it), an overclaim ('never crashes' where the spec only promises bounded reads and allocations), a wrong example, and a dependency list that mixed library and tool deps. These are exactly the errors a single writer agent makes when asked for 'why'.
Lessons: - When records hold little design rationale, phrase the reason as the design goal ('to keep point reads cheap'), never as a measured fact. Only numbers that already appear with a MEASURED label may appear. - Keep a list of reasons deliberately left out (sensitive or unrecorded) for a human to decide. Don't let the writer guess them. - Run the real banned-terms guard at apply time. A writer working with a placeholder list can't certify it.