Your docs are already lying to you
Here is a small story from a single afternoon of building. It is not dramatic. Nothing broke in production. No data was lost. But it cost real hours, and the reason it happened is the entire reason this product exists — so it is worth telling plainly.
The setup
We run more than one coding agent on the same project. Different sessions, sometimes different models — one writing code, one reviewing, one running tests. Standard stuff now. To keep them coordinated, the project has the usual artifacts: an ARCHITECTURE.md, a pile of design docs, a README that someone updated three weeks ago and swears is current.
That afternoon, an agent picked up a task. It needed to understand a decision we had made about the system — why a piece was built the way it was. So it did the sensible-looking thing: it opened ARCHITECTURE.md, read the relevant section, and got to work.
The section was wrong. Not maliciously, not even carelessly — just old. The decision had moved on. The doc had not. The agent built confidently on top of a fact that had been true two weeks ago and was now quietly false. We caught it, but only after the work had gone a direction it shouldn't have. Then we backed it out and did it again.
The part that matters
The failure was not the stale doc. Stale docs are a law of nature; fighting them is like being annoyed at gravity.
The failure was the retrieval path. The agent had a choice it didn't know it was making. It could ask the living system — "what did we actually decide about this, and when?" — or it could read a file that happened to be sitting in the repo. It read the file. The file looked authoritative. Markdown looks authoritative; it has headings.
And this is the thing about documentation that nobody likes to say out loud: a document is a photograph. It is true at the instant the shutter closes and decays from there. It has no idea the world moved on. It will hand you a two-week-old fact with exactly the same confidence as a two-minute-old one, because it cannot tell the difference. It doesn't know what it doesn't know.
A human half-notices this. You read a README and some background process whispers this might be old. An agent has no such instinct. It treats the file as ground truth because the file gave it no reason not to. The doc didn't lie on purpose. It lied because lying is what frozen things do when the world keeps moving.
Frozen vs. live
So we drew a line we should have drawn earlier, and it's simple:
Documentation is frozen. A substrate is live.
A frozen artifact — a .md file, a wiki page, a comment block — captures a moment and then drifts out of sync silently. You don't get an error when a doc goes stale. You get a confident wrong answer, which is worse.
A live substrate is the opposite. When the agent asks "what did we decide about X," it isn't handed a file someone may or may not have updated. It's handed the current state, with the decision that superseded the old one already in front of it, timestamped, attributed. If the answer changed, the answer it gets changes too. There is no separate "update the docs" step to forget, because the place you read from is the place you wrote to.
That's not a feature we bolted on. It's the whole bet. The reason to put your decisions, your context, and your hard-won lessons into something an agent queries rather than something it reads is that querying gets you the world as it is now, and reading gets you the world as it was whenever someone last remembered to type.
Why this gets worse with more agents, not better
The instinct is that more documentation fixes this. Write more down, write it more carefully, and the agents will stay aligned.
It's backwards. Every doc you add is one more photograph that starts aging the moment you save it. Multiply that across a repo and you haven't built a shared brain — you've built a gallery of slightly-wrong snapshots, each one confident, each one a trap for the next agent that trusts it.
And with multiple agents the blast radius grows. One agent reads the stale section, builds on it, and writes its output back into the repo — now reinforcing the wrong picture for the next agent. The error compounds. Git will faithfully tell you what changed and when. It will not tell you that the change was based on a decision we reversed last Tuesday. That "who and why," kept live, is the part that actually keeps a swarm of agents pointed the same direction.
The discipline
We came out of that afternoon with one rule, and it's almost embarrassingly small:
Don't assume. Ask the live source.
When an agent is about to act on "the way this works," the correct reflex is not open the doc. It's query the substrate. If the substrate doesn't know, fine — then you've actually discovered a gap, instead of inheriting a lie.
The doc can stay. Write the README, keep the architecture overview — they're useful as orientation, as the human-readable front door. Just stop treating them as the source of truth for a decision that can change. The source of truth has to be the thing that's still alive when you read it.
The honest version
We didn't get this right the first time. We had the docs, we had the substrate, and an agent still reached for the photograph because the photograph was right there and looked official. Knowing the better path and taking it are two different things — which, it turns out, is its own lesson, and one for another field note.
But the core of it stands, and it's the sentence we keep coming back to:
A frozen file will hand you yesterday with a straight face. Ask something that's still alive.
Retia is a structured, queryable context layer for AI agents — the live substrate this note is about. If your agents are still reading stale files to figure out what you decided, that's the problem we built it to remove.