Keeping Documentation Up to Date
Code often changes first, and the documentation lags behind. The next coding agent reads the document anyway and works from a description the code no longer matches.
I have caught the more dangerous version during PR review. A feature introduces a framework or changes a design boundary, but the PR presents the choice as implementation detail. The team never accepted the decision, and no ADR or design document records it. Later an agent finds both the old and new framework in the codebase and uses both. From the agent's view, both are established patterns.
The smaller cases are merely annoying. I have seen an outdated instruction make the agent build and test the entire codebase after a Markdown or configuration edit. You notice because you sit there waiting for work nobody wants. An undocumented framework decision is harder to catch. By the time it surfaces, the wrong choice looks like an ordinary part of the implementation.
Some tests fail when code changes, giving the team a signal to inspect. Prose has no equivalent by default, and an absent decision has no file to become stale. This chapter addresses the part a deterministic check reaches. The missing-decision problem still depends on review and team discipline.
This chapter covers one narrow extension of verification: give important documentation a feedback loop. A tripwire turns silent drift into a visible signal.
A release should leave the codebase ready for the next agent session. This chapter covers a cheap part of that work: identifying documents that became suspect after the source moved.
Prevention comes first. Spec Lifecycle puts the docs update inside the change, as tasks in the same pull request as the code. The tripwire here catches the documents that rule missed.
Sources: The release-to-next-session boundary and documentation tripwire are this book's workflow synthesis, informed by the author's PR-review examples above.
The asymmetry
Tests sometimes expose a mismatch after code changes because a failing assertion produces a visible signal. A test that never covered the changed behavior stays green.
Documentation has no equivalent check by default. A design note describing an old retry policy does not fail. An agent instruction file pointing at a renamed file passes every check unless a structural link validator catches it, and a README documenting last month's module boundary still renders cleanly on GitHub.
An agent can change code and leave the surrounding prose untouched. The build still succeeds unless a check links that prose to the changed area.
The failure is not only reader confusion. The next agent session starts from false inputs. A stale architecture note makes the agent add a layer the system no longer uses or follow a codebase rule the team already removed because the instruction file still lists it.
This book calls the immediate failure context poisoning: one stale document steering the next implementation session toward obsolete behavior.
Sources: The stale-document example and the term "context poisoning" are this book's synthesis.
A stable link from prose to code
The verification move is familiar by now. Do not match text. Match identity.
AC IDs and Coverage made tests durable by linking each acceptance scenario to a stable Acceptance Criterion ID (AC ID). The scenario text gets rewritten, and the test moves files, but the ID remains stable, so the link between intent and evidence remains intact.
Documentation needs a lighter version of the same move. Each important document carries a small front matter block naming the code paths the check watches and the date somebody last checked it against those paths:
---
tracked-paths:
- services/payments/src
- services/payments/build.gradle.kts
content-verified-at: 2026-06-25
---tracked-pathslists the repo paths whose changes might invalidate the document.content-verified-atrecords the last date somebody checked the document against those paths.
Once the fields exist, the check asks a mechanical question: did one of the tracked paths change after content-verified-at?
This is not a field standard. I use it here as a working synthesis of the AC-ID idea for prose: one stable marker in the prose, one reference target in code or docs, and one check that verifies the link.
Sources: The front matter marker and field names are this book's synthesis from AC-ID verification logic applied to prose.
What the check looks for
The minimum useful validator is content-blind and deterministic. Content-blindness is what keeps it cheap enough to run on every change.
First, verify the reference itself. Every entry in tracked-paths must resolve. A document pointing at code no longer present is already wrong in one concrete way.
Second, compare the review date to the source history. If the latest commit touching one of those paths is newer than content-verified-at, the document is now suspect. The check does not claim the prose is false, only that nobody has confirmed it since the source changed.
Three states are enough for the repo-local documentation drift check:
broken-ref: a declared source path no longer resolvesstale: a tracked path changed aftercontent-verified-atuntracked: a handwritten document has no marker yet
broken-ref should fail the build. stale is better as a warning at first, then a build failure later if the team wants a ratchet. untracked stays warn-only so adoption does not turn into a migration project before the first signal appears.
The useful twist is diff scoping. Checking only documents changed in the Pull Request (PR) fails the moment somebody forgets the doc update. The validator should also pull in tracked documents whose tracked-paths entries intersect the code changed by the PR.
Sources: The tracked-paths, content-verified-at, state names, fail/warn policy, and diff-scoping rule are this book's synthesis from AC-ID verification logic applied to prose.
Put the check in the workflow
Tell the agent which documents need markers and what to do when a code change produces a stale warning. Run the validator during the task so broken references surface before review.
For this book's workflow, configure the validator as a required Continuous Integration (CI) check. Treat broken tracked paths as failures. Review still decides whether the marked document describes the code accurately.
Sources: The validator placement and failure policy are this book's workflow guidance.
Why this belongs in verification
This is not a general documentation chapter in disguise. The scope is narrower: keep the files agents load aligned with the code agents are changing.
Docs > Specs > Code argued for design intent above code because this book treats generated code as the more disposable artifact. Once you accept that order, stale documents stop being a writing problem. They become a quality problem.
Verification closes the code gap with tests. A documentation drift check closes part of the prose gap. Both follow the same control pattern:
- attach a stable link to the artifact under review
- run a deterministic check against the link
- expose failure where the team already pays attention, in CI
The check does less than a behavior test with useful assertions. A documentation drift check flags a tracked source change after the recorded review date. It does not verify the prose. That weaker signal still earns its keep because the default is silence.
Limits worth naming
The signal is blunt. A commit touching a tracked directory marks the document stale even when the change was a rename, a comment edit, or an internal helper the document never mentioned.
The date is a bookkeeping marker, not evidence of careful reading. Bumping content-verified-at silences the warning.
Cross-cutting documents are awkward. A design note covering four subsystems and two team boundaries has no tidy sibling path list. Those documents need manual tracked-paths entries, and many teams will defer the work.
These limits are why I still regard documentation freshness as one of the largest unresolved parts of the practice. The control is a tripwire, not semantic verification. It points at prose somebody needs to inspect. It cannot tell whether an important design change is missing. It will also accept a new date from somebody who never read the file.
The checkpoint checklist places this inspection before implementation and the documentation update before merge.
Sources: This chapter's extension of AC-ID verification logic from tests to prose is this book's synthesis.