The documentation was the defect
Software architecture · 2026-09-13
The one defect shape that keeps recurring, at three scales, and the only kind of evidence that stops it: a gate seen red.
The incident
A document said the covers were made with a particular image model. A script obeyed the document. Four hundred and fifty-nine covers were regenerated on a model that had been banned. The script was correct against the documentation, and the documentation was the defect.
The same shape, one size down
A comment says "see stripe-customers.ts". The reader greps for it, finds nothing, and concludes the comment means something subtler than it does. Measured across one codebase: seventy-one comments named files that no longer existed, three of them the headers of stylesheets nothing imported. The audit that should have caught them read only paths in backticks; a file name in prose is a mention too.
A roster does not go blank when it goes stale; it goes confident. Three personas on a project table were simply wrong, and the table still read as sorted and authoritative.
What actually stops it
Not more documentation. Generated documentation, checked on every build, so a fact cannot be typed. And for every guard, one piece of evidence: plant the defect it claims to catch, run it, watch it go red, restore the tree. A green suite is the easiest thing to fake, and a guard that has never been seen red is a decoration.
The analogy is a smoke detector. Nobody trusts one because it is quiet; they trust it because they pressed the test button and it screamed.
document says X ──► script obeys ──► 459 wrong covers comment says "see foo.ts" ──► foo.ts is gone ──► reader trusts the comment fix: generate the fact, and press the test button on every gate