Documentation has always gone out of date. That isn’t the interesting part.

The interesting part is that the loop which used to keep it roughly honest depended on a human pace, and that pace is gone.

The loop that used to work

It was never formal, but it worked often enough. You changed some code. You held the change in your head, because you’d just spent two days on it. Somewhere near the end you thought: the onboarding page says we use the old queue. And you fixed it, or you didn’t, but at least you knew.

Three things made that possible. The change was small enough to remember. It took long enough that documentation crossed your mind. And you wrote it, so you knew what it invalidated.

An afternoon with a coding agent breaks all three at once.

Forty files touched in one session. A refactor that would have been a sprint with a design doc lands before lunch. And critically: you didn’t write it. You reviewed a diff — probably well, but reviewing a diff and holding a change in your head are different activities. You know what the code does now. You have a much weaker sense of what it used to do, and that difference is precisely what tells you which pages just became wrong.

Ask an engineer which docs their last agent-assisted refactor invalidated. The honest answer is usually a shrug. Not carelessness — they genuinely don’t know, and there’s no way to find out short of reading everything.

The part that’s actually new

Here’s the failure mode we didn’t have five years ago.

Agents read your documentation. That’s the point of putting a wiki in the repo — so the tools working in your codebase have context beyond the current file. Mine writes a Claude Code skill into the repo for exactly this reason.

Which means a wrong page is no longer just a human problem. It’s an input.

An agent reads a page describing the queue architecture you replaced in April. It writes code against the architecture in the page. That code gets reviewed by someone who half-remembers the migration, looks plausible, and merges. Now the codebase contains a fresh implementation of a pattern you deliberately abandoned — and the page that caused it is still sitting there, still wrong, ready for the next session.

Stale docs used to decay quietly. Now they actively generate work. Drift compounds instead of just accumulating.

I don’t want to overstate this — a good reviewer catches most of it, and agents don’t blindly follow docs over code they can read. But the direction is clear, and it’s the opposite of self-correcting.

What has to change

Not “write better documentation.” That advice has been available for thirty years and hasn’t worked once.

What has to change is that invalidation becomes mechanical. If a page declares which paths it covers and which commit it was last verified against, then “what did this refactor invalidate?” stops being a memory exercise:

$ git log --oneline -1
a1b2c3d  refactor billing to the new adapter

# the wiki, on the next build
billing/refunds.md    may be outdated
billing/invoices.md   may be outdated
6 other pages unchanged — nothing to review

Two pages to look at, not two hundred. That’s small enough to actually do, which is the only property that matters.

And this is where an agent stops being the cause and starts being the fix. Re-reading two changed files and correcting the prose that describes them is a genuinely good use of one: bounded, verifiable, and the diff is right there. It’s a far better task than “write our documentation,” which is where people usually point them and where the output usually reads like it.

The circularity you should worry about

There’s an obvious objection, and I’d rather raise it than have you find it.

If an agent wrote the code, and an agent updates the docs describing that code, what exactly has been verified? You’ve automated both halves of a loop whose whole purpose was to be a check on itself.

I don’t think that’s fatal, but it does constrain the design. It’s why the tool I built marks pages it couldn’t confidently update as needing review rather than rewriting them on a guess, and why a sync run is meant to land as a small reviewable commit rather than pushing straight to main. The agent narrows the work; a human still signs off. Remove that and you’ve built a machine for generating confident, wrong prose at scale.

The honest framing is that this doesn’t remove human judgment from documentation. It removes the searching — the part where you’d have to know, unprompted, which of two hundred pages your afternoon just broke.

Nobody was ever going to do that part anyway.

The mechanism behind this — why two lines of frontmatter are enough to make a page checkable — is in the previous article.