The Convention Lied

The rule had been true when someone wrote it. “All new services go through the shared gateway.” It sat in the conventions file for a year, accurate and unremarkable, until the day we moved off the gateway and forgot the file existed. The sentence never changed. The world underneath it did.

Nobody noticed, because nobody reads the conventions file. That was always its quiet mercy. A human joining the team would have skimmed it, felt the dust on it, and asked someone which way things actually work now.

The agent didn’t skim. It read the line, believed it, and wired a brand-new service straight through a gateway we’d spent a quarter tearing out. It worked flawlessly, right up until the new service’s calls started vanishing into a gateway we no longer ran, and a customer noticed before our dashboards did. It never hesitated, because the file gave it no reason to.

Rot isn’t gradual. A document stays perfectly fine right up until the instant something acts on it, and then the whole cost of its being wrong arrives at once, with interest.

It did careful, competent work in service of a fact that had died three months earlier.

We used to treat old docs as clutter, a mess to tidy up eventually. That framing is finished. An old doc is now a loaded instruction sitting in the path of a tool that does exactly what it says.

The fix isn’t heroic. Keep the files that matter small enough to actually maintain, close enough to the code that changing one means changing the other, and let the agent that reads them also check them. Turn the reader into the proofreader.

Three months. That’s how long a good rule stayed true before it started lying, and how long it took anyone to notice.

The docs didn’t fail the day they went stale. They failed the day something believed them.