*Published July 14, 2026* --- The fix for spec rot has a nice symmetry. Specs go stale because humans write them once and never touch them again, so make the spec bidirectional: let the agent write back what it learns during implementation, and the document stays true. [Augment Code put it cleanly](https://x.com/augmentcode/status/2025993446633492725): a spec that isn't updated becomes a lie the agent trusts. That's correct, and it's the narrowest and most failure-prone of the three things you need, the one this year's tooling reaches for first. If it's the only one you reach for, your living spec will keep lying to you. It will just lie about different things. ## The problem is real, and older than the agents Documentation rots fast in a changing system, and unevenly. Google's [SRE book](https://sre.google/sre-book/accelerating-sre-on-call/) puts it sharply: stale docs barely hurt the senior engineer, who keeps the system in their head, but they wreck the newcomer, who has no choice but to trust what's written. The prescribed fix isn't automation. It hands the new hire the most out-of-date sections to overhaul, reviewed by the people who actually know. Swap "newcomer" for "agent" and it transfers. The agent is the ultimate low-context reader: no memory of last week's decision, no hallway conversation, no instinct that the config comment is a year stale. Whatever the spec says, it believes. A missing document makes it guess from the code, which is at least visible and recoverable. A wrong one makes it act on the lie, confidently, with no signal that anything is off. ## Fix one: write-back, and where it fails Write-back works for a specific thing: the reasoning the code can't hold. When the agent works out why the retry budget is three and not five, that the vendor's rate limit collapses above three and an incident last year proved it, that belongs in the document. The value three lives in the code; the reason does not. ADRs are the disciplined version, the thinnest layer of docs that captures the decisions code can't communicate. Two problems. First, an agent can write back garbage, and a confidently wrong update becomes the source of truth every downstream agent trusts. The failure is silent, because the point of the document is that people stop re-deriving it. A write-back loop needs a second thing that reviews the write-back, a cost the tidy version never mentions. Second, the most influential document in software already argued the opposite. The [Agile Manifesto](https://agilemanifesto.org/) watched teams document themselves into irrelevance and concluded: working software over comprehensive documentation. Its answer to rot was less document, not a better-maintained one. If your fix is "write more, more often," you owe the reader an account of why the canonical answer was "write less." That account is that Agile was right about prose and wrong to stop there, because one form of specification doesn't rot the way prose does. ## Fix two: make the spec executable Gojko Adzic's [*Specification by Example*](https://gojko.net/books/specification-by-example/) supplies the move Agile missed. Express the spec as an executable test and it can't silently drift from the code, because the moment it drifts, it fails. The spec and the check are the same artifact; agreement is enforced on every run, not maintained by discipline. That beats write-back at the one thing write-back is worst at: staying in sync. But it is narrower than "the test is always right." An agent can write a test that encodes the wrong intent, and it passes, green and lying, exactly like a confidently wrong prose update. Executability doesn't make the agent correct; it makes the artifact unable to drift after the fact. So an agent-written test earns the same review a write-back does. What you stop paying for is the slow failure, where document and system diverge over months with nobody watching. The old cost objection, that tests were too expensive to write, has collapsed now that the agent writes them. (That's its own essay.) So where you can encode the intent, make it a test, a type, a contract, and reserve write-back for the residue that resists encoding. One domain inverts, worth naming so the argument doesn't overreach: in formal methods the spec is the authority and the code conforms to it. [AWS documented using TLA+ this way](https://cacm.acm.org/research/how-amazon-web-services-uses-formal-methods/) back in 2015, on critical systems, spec as trusted source, implementation checked against it. That's real, but design-time and narrow. For the everyday case, where the implementation discovers what the design didn't know, the direction runs the other way. ## Fix three: the layer no document reaches Neither write-back nor executable specs knows what your system actually does in production. [Charity Majors](https://thenewstack.io/honeycombs-charity-majors-go-ahead-test-in-production/) has spent years on the observability version of this: you cannot predict where a distributed system will fail, mirroring staging to production is a fool's errand, and the only way to know what production does is to watch it run. Point that at specs and the conclusion is unavoidable. A spec captures the developer's model at write-time; it cannot anticipate the combinatorial explosion of real load and states no one enumerated, the same explosion no staging environment reproduces. Only observability tells you what happened at 3 a.m., under a traffic spike, with a half-deployed config. And it worsens as AI writes more code faster: more code, more runtime combinations no spec, however live, ever considered. ## Match the mechanism to the layer So a spec has layers, and each stays true by a different mechanism: - **Encodable intent** stays true by being executable. Tests, types, contracts. It can't drift without failing. - **Non-encodable intent**, the decisions, stays true by write-back into a thin prose layer, reviewed, because the agent can be confidently wrong. - **Runtime behavior** stays true by observability, because no document written ahead of time can know it. You don't need new tooling to start, just a question. When you reach for the spec, ask what kind of fact it is. A rule you can assert goes in a test. A decision you can only describe goes in the reviewed prose layer. A behavior you can only observe goes on a dashboard. The mistake worth naming is conflation: expecting write-back to catch a runtime bug, or trusting a prose spec to last as long as a test suite. The living-spec enthusiasm gets one layer right and assumes it covers the other two. A spec is a lie waiting to happen; it always was. Keeping one document perpetually true is a fight you lose slowly, so stop trying. Match each layer to the mechanism that can keep it honest, and don't reach for a living document just because it's the thing everyone's talking about this year.