Docs Rot Because Humans Maintain Them
Documentation scales with the system; human attention doesn't — the only fix is to stop relying on humans to maintain it.
Two Tracks, Two Roles
Before diving in, two lane statements.
The prerequisite track — documentation-is-king — taught the doctrine: what each doc type is for, why docs are the agent interface, and that freshness signals and CI gates exist. The Keeping Docs Alive lesson in that track introduced the idea that count-integrity tests and link checkers could block merge on drift. If you have not completed that track, the concepts here will land better after you do.
The sibling track in this category — agent-knowledge-systems — is about the agent's MEMORY: what the agent learned, stored, and supersedes over time. Memory is earned from experience; it is updated when the agent observes something new. This track is about the repo's DOCS: what the team declares true, verifies with CI, and maintains as authoritative. The enemy is the same — rot — but the artifact is different. Memory rots when nothing supersedes a stale observation. Docs rot when nobody updates a declared fact. The automation strategies diverge accordingly.
This track BUILDS the machinery the prerequisite described. Drift test suites. Generator scripts with ownership markers. A doc-bot that opens PRs instead of pushing to main. Freshness SLO gates that block CI. That is what you are here to implement.
The Arithmetic of Rot
Documentation rot is not a failure of discipline. It is a failure of arithmetic.
Consider a moderately active codebase: sixty documentation files, each requiring an average of thirty minutes to update when the thing it documents changes. The system ships eight changes per sprint that each affect at least one doc. That is four hours of documentation maintenance per sprint — before accounting for the fact that one change often touches multiple docs.
Four hours is a lot of time to consistently spend on documentation under normal sprint pressure. Under a deadline, it is the first thing cut.
The rot economics diagram makes the scale visible. API references at high churn are critical-risk within a few sprints without automation. Context files — the newest doc type — are critical-risk because they are read by agents on every session, meaning every wrong fact immediately produces wrong agent output. A context file with an incorrect deployment target does not silently mislead someone; it produces a wrong deployment the same morning the agent reads it.
The math only gets worse as the system grows. Docs scale with the system. Human attention does not. By the time a system has a hundred documentation files at medium-to-high churn, the maintenance load exceeds what any team can sustain by hand — even a disciplined one.
The Agent Inversion
For most of software history, documentation rot was a maintenance inconvenience. A wrong README cost someone fifteen minutes of confusion before they asked a colleague. A stale runbook occasionally sent an engineer in the wrong direction for thirty minutes. The costs were real but diffuse and invisible until a sufficiently bad incident surfaced them.
Coding agents changed the calculus. Claude Code, and tools like it, read your documentation before touching a single line of code. Not once during onboarding. Every session. Every dispatch. Every time a new agent instance is spawned to fix a bug or add a feature.
This one shift inverted the rot loop. A stale doc that human readers would skeptically verify before acting on gets read literally and acted upon immediately. A context file that says the production server is at a now-decommissioned address produces a wrong deployment the same session. An API reference with a removed flag produces a broken implementation in the same PR. The feedback loop compressed from months to hours.
Documentation automation was optional hygiene in the human era — good to have, easy to defer. In the agent era it is interface maintenance. The docs agents read are the interface between human intent and agent execution. Wrong interface, wrong output, every session.
The Automation Ladder
There is a spectrum of doc-maintenance maturity. Understanding where each doc type currently sits on this ladder tells you where to invest first. The ladder is graded A0 through A4 and applies per doc type — one repo can have its changelog at A4 while its runbooks sit at A1. (The capstone lesson introduces a separate L0–L4 repository maturity model that grades the whole repo at once; the two scales are related but deliberately distinct, so keep the A-labels and L-labels apart in your head.)
A0 is the worst position: no documentation at all. Every agent session starts blind; the agent invents orientation context it cannot verify, and errors compound silently.
A1 is where most teams live: docs exist, maintained by a named owner under best effort. This works until the owner changes projects or a deadline hits. A1 docs decay on a predictable schedule because there is no enforcement mechanism.
A2 adds CI gates: drift tests that assert countable facts, link checkers that verify paths, schema tests that pin types to source. The critical insight about A2 is that it does not require automation of the doc content — it only requires automation of the verification. A human still writes the doc; CI verifies that specific claims in it remain true after each merge.
A3 inverts the generator relationship: instead of writing the doc by hand and testing its claims, a generator script produces the doc section from a source of truth. The source changes; the doc regenerates. A3 is appropriate for anything that is computable — type lists, key-files tables, counts, API reference sections, changelogs.
A4 adds a doc-bot layer: automated commits that open PRs for mechanical changes. Human reviewers see only the diffs that require judgment. A4 is where this track ends, with the doc-bot pattern in the doc-bot lesson and the full safety model in the doc-bot-safety lesson.
The target is not A4 for every doc type. Runbooks and ADRs require human judgment in the prose — they belong at A2 (drift-tested) plus A3 for any computable sub-sections. The goal is to distribute each doc type appropriately across the ladder based on how much of its content is computable versus judgmental.
What This Track Builds
This track is ten lessons, each building one component of the self-maintaining doc stack:
- Drift detection: vitest tests for counts, links, schemas, and command references
- Generated references: the generator pattern — one source of truth, many projections, with BEGIN/END ownership markers
- The doc-bot: automated updates under the surgical-edit contract
- Specialized domains: runbooks that stay true, changelogs on autopilot
- The doc registry: the DocRecord shape as the index over all living docs
- Freshness SLOs: the CI gate that blocks on expired docs
- The safety model and capstone: mechanical-vs-semantic routing, and the system assembled end to end
By the end, you will have a working implementation of each component. Not a design spec — a running system.
The BuildChallenge for this lesson starts at the foundation: the canonical DocRecord shape that every subsequent lesson in this track builds on. Get the shape right now, and every challenge that follows compiles without changes to the interface.