Intent Is Not Reality

Almost every project document I have inherited fails in the same way. It opens describing a plan, drifts into describing the system, and somewhere in the middle stops being true. Nobody decided to lie. The doc just quietly aged past the code, and because it read confidently, it kept being trusted long after it stopped being right.

The root cause is not laziness. It is that the document was trying to hold two different kinds of truth in the same place: what the team intended to build, and what is actually true right now. Those two things change on completely different clocks, and when you store them together, the slower one drags the faster one out of date.

Two kinds of truth

Intent is stable. The objective, the direction, the constraints you have agreed not to cross: these move rarely, and when they move it is a real decision worth recording. Verified reality is the opposite. It changes every time you merge, deploy, or fix something. A file that mixes them is stale by construction, because half of it is supposed to sit still and half of it is supposed to move.

So separate them by ownership. I keep a small set of documents where each one owns exactly one kind of truth:

• Intent. The approved objective, the direction, the durable constraints. What we are trying to do and what we refuse to do. This changes only when someone approves a change.
• Verified reality. What is actually true and working now, with evidence. Commands that have been run. Tests that pass. This is allowed to contradict the intent, and when it does, that gap is information, not a bug in the doc.
• Rationale. The substantial decisions and why they were made. The context that would otherwise evaporate the moment the person who made the call moves on.
• Active work. The current plan, progress, and blockers. The one file safe to be messy, because it gets cleared when the work lands.

The discipline is simple to state and easy to break: update only the document whose kind of truth actually changed. When you ship a feature, verified reality changes. The intent usually does not. Editing the intent file to describe a new feature is how the two collapse back into one and start rotting again.

The gap is the point

The most useful move in this whole setup is giving verified reality permission to disagree with intent. If the plan says the system does X and the system does not yet do X, the honest state file says so, plainly, as a known gap. That sentence is worth more than a paragraph of aspiration, because it tells the next person exactly where the edge of "real" is.

Teams resist this because a gap looks like failure on the page. It is the opposite. A documented gap is a system that knows itself. The dangerous project is the one whose docs describe only the intended end state, so you cannot tell from reading them which parts exist and which parts are still a wish. That project feels further along than it is, right up until someone builds on a part that was never real.

Unverified is worse than absent

There is a rule I hold in my own work that started in AI and turned out to be a documentation rule too: an unverified fact is worse than no fact.

In an AI system, a confidently stated number that nobody checked is more dangerous than an honest blank, because the blank makes you go look and the number makes you stop looking. A hallucinated metric in a model's answer and an unverified metric in a status doc fail in exactly the same way. Both borrow credibility they have not earned, and both get repeated by the next reader as if they were solid.

So the same guardrail applies. If a number, a claim, or a capability has not been verified, either leave it out or mark it clearly as unverified. Marking is not weakness. It is the difference between a document that helps and a document that quietly launders guesses into facts. I would rather ship a state file full of honest blanks than one full of confident sentences I cannot stand behind.

Decisions are for whoever inherits the code

The rationale layer is the one people skip, and it is the one they miss most later. Code shows you what the system does. It almost never shows you what you are not allowed to do, or which of two reasonable options was deliberately rejected, or why the obvious approach was the wrong one here.

A short decision record fixes this. Not a heavy process document. A few lines: what we decided, what we chose against, and the reason. The value shows up months later, when someone looks at a strange choice, assumes it was an accident, and "fixes" it back into the exact problem it was avoiding. The decision log is a message to that person. It says: this was on purpose, here is the constraint you cannot see from the code.

Write these for your future self as much as for anyone else. The context that feels too obvious to record today is precisely the context that will be gone in three months.

Why this matters more now

This was always good practice. It is becoming a hard requirement, because the readers changed.

When the only readers were people, a stale doc was a slow tax. A teammate would notice the drift, ask in chat, and route around it. An agent will not. It reads what you wrote, treats it as current, and acts on it. If your intent and your reality are tangled in one aging file, the agent inherits the tangle and builds on the wrong half with total confidence. The blast radius of a stale document goes up sharply the moment a machine is doing the reading.

The good news is that the structure that makes docs legible to an agent is the same structure that made them legible to humans all along. A clear front door of a few current, non-overlapping files. One owner per kind of truth. Verified state kept separate from intended direction. Decisions recorded where they can be found. None of this is new. It just stopped being optional.

The short version

If your documentation keeps going stale, the problem is usually not effort. It is that one file is trying to be a plan, a status report, a decision log, and a spec at the same time. Split those apart by what kind of truth they hold, let reality contradict intent out loud, refuse to write down anything you have not verified, and record the decisions the code cannot explain. Do that, and your docs stop being a liability the day someone, or something, actually needs to trust them.