Stop Documents from Rotting: The Document Lifecycle Mechanism in the Agent Era

When agents become the primary authors of code, documents rot even faster. The rules are written in the spec, yet documents that violate them sit right next to the spec. This isn't hypothetical — it's the actual state recorded during a document cleanup of an enterprise payment approval system.

The original author provides the complete answer in the fourth article of the series: from principles to mechanisms to breaking points, an engineering solution that keeps documentation alive along the time dimension. The first three articles address "which document to read," "where to find it," and "which copy to trust." This one tackles the last link — after writing, how do we keep it from rotting?

Three Forms of Document Rot

A document health check exposed problems with one thing in common: the rules were written long ago, yet documents violating them sat right beside the rules. The document model spec defined 8 states, but the plan index actually contained 9 spellings — completed, done, and free-form Chinese all mixed together. The spec said the index should "keep only six columns," but there were actually 8, with another 4 rows having the wrong column count — and nobody noticed.

Categorizing the symptoms, document rot takes three forms. Work was done but not written back: implementation records are missing, and the next agent can only read the plan. Conventions depend on self-discipline: the glossary, column counts, and ID formats exist only in the spec, with no checks at commit time. Old facts refuse to exit: date banners, stale overviews, and outdated conclusions in personal memory linger on.

The root cause is consistent: when documents should be written, where they should be written, who checks them, and when they should retire — these were only ever "expected," never designed. The original author points out a key fact — without machine enforcement, noticing is not the same as fixing. The cheapest option is to leave a note; once that note is written, the problem becomes a "known issue" that never gets fixed.

Three Design Principles

Principle One: Write-back is part of the change. The definition of "done" includes writing documentation back — implementation records, status in the index, cases, specs, manuals. If it should have been written but wasn't, the change isn't complete. How it was actually done and where it deviated from the plan exist only in the session that executed the work; when the session ends, the information is gone.

Principle Two: Machines enforce conventions; humans only adjudicate. The same agent in two different sessions might write the spec and then violate it. Anything parseable — the glossary, IDs, metadata fields, table headers — goes to the checker. Humans appear only where machines can't judge: is the definition correct, should this exception be approved, should this issue be fixed.

Principle Three: Zero tolerance at the entry layer; a ratchet-only baseline at deeper levels. Every session enters through the entry point, and a single error there gets executed verbatim by every session, so it must be zero. Deep documents are a massive backlog; demanding a one-time cleanup to zero is like halting work to sweep the floor. The practical approach is to record today's numbers as a baseline — new issues must not raise it, and each fix lowers it by one.

The Write-Back Loop: Giving "Done" a Definition

Principle One becomes a table: "change type → what must be written back before completion → who checks." The "who checks" column cannot be empty. The write-back rule existed long before the cleanup — filling in the "actual execution record" in the plan after development, updating the roadmap at the same time — but execution relied entirely on self-discipline, resulting in a batch of completed work packages with no implementation records.

Lower the barrier, and write-back actually happens. Requiring even small defects to produce the full four-piece set usually results in only a requirements file, with write-back skipped entirely. The lightweight form needs only a requirements document, but when the status moves to "implemented," the document must gain an "implementation record" section.

Deliverables live inside the loop, outside the route. User manuals, changelogs, and handoff notes serve business users and operations — agents maintain them but don't learn working methods from them. The routing table only records "which change requires updating it." The original mentions that the user manual was eight days late — that was the cost of one missing row.

From Incident to Check: The Enforcement Ladder for Rules

After each incident, a rule goes through a pipeline: incident → written rule → check. The problem is it often stops halfway. The author arranges rule enforcement into a ladder from weak to strong:

1. Narrative: write the incident as a story — only sessions that happen to read it are affected.
2. L0 one-line rule: written into the entry file with a reason and a link — every session reads it, but compliance depends on the agent's self-discipline.
3. L1 detail: explain how to do it and what counts as a violation — the rule goes from "known" to "executable and judgeable."
4. Code review check: violations are caught by a reviewer against a checklist before merge — the reviewer is often another agent.
5. Shared helper function or automated check: the wrong way simply can't be written, or it goes red the moment it runs — no longer relying on anyone remembering.

The higher it climbs, the less it depends on "being read and remembered." Two contrasting cases are given. The magic-number header check for download endpoints climbed to level five: the test changed from only checking file name suffixes to validating the magic number at the start of the file (the fixed bytes identifying the format) via a shared helper — the correct approach became the cheapest approach. Meanwhile, the rule "check all parallel branches and worktrees before taking a migration number" remains a manual rule, stopped halfway.

The pipeline asks only one question per rule: can it climb one more level? Rules stuck at lower levels aren't necessarily wrong — some judgments can't be made by machines — but it must be explicit that the rule depends on self-discipline.

The enforcement ladder shares its roots with the "poka-yoke" concept in cybernetics: level five's "shared helper function or automated check" corresponds to the Japanese term "ポカヨケ (poka-yoke)" — making the wrong approach physically or structurally impossible rather than relying on the operator to remember the rule. The first four levels are essentially different intensities of "reminder + human/agent judgment." The reason it's drawn as a ladder rather than a binary classification is to give every rule a direction to pursue: if it can climb from L0 to code review, don't stop at L0; if it can climb from review to automated check, don't stop at review.

The origin of the "ratchet-only" baseline: this technique is known in static analysis and technical debt management as a "ratchet" — similar to Rust's clippy baseline or SonarQube's quality gate. The core is not demanding a one-time cleanup of the backlog, but freezing the current violation count as a non-increasing ceiling, with each fix lowering the ceiling by one — forming a one-way convergence over time. It breaks "the big cleanup" into "each change doesn't worsen things," which naturally matches the short session lifecycle of agents.

doc-lint: The Test Suite for Documentation

doc-lint is the core product of this cleanup — a script that checks documentation, with 36 check codes and 62 of its own unit tests. The checks cover several groups:

IDs and registration: stable IDs are unique, work package directory names mechanically correspond to IDs, and every work package is registered in the index — otherwise it doesn't exist for an agent entering from the index.

Glossary and metadata: status and type can only take values from the glossary, the metadata block must be complete, and Replaced by is a required key. There's a detail here — the field can be filled with none, but it can't be omitted, otherwise the rule "when you read a superseded document, jump first" would spin in circles. The tool only checks whether the key exists, not whether the superseded document actually has a new ID filled in — that half still relies on review.

Index shape: the table header has a fixed six columns, each row has a consistent column count, titles and "next steps" have length limits, and date banners are prohibited.

Links: a single broken link at the entry layer is an error, and repo-wide broken links must not exceed the baseline (corresponding to Principle Three).

Output is one issue per line, with check code, file, and reason — an agent can read it and fix it immediately. The tool also conveniently does two things that "make the correct approach cheapest":

python3 scripts/doc-lint.py
python3 scripts/doc-lint.py next-id --type <type>
python3 scripts/doc-lint.py gen-views

In order: run all checks; return the next free ID so number-taking no longer depends on the agent counting directories itself; regenerate derived views from the case master table. Views must not be hand-edited — inconsistency with the master table is an error.

Stable-State Rules and New Project Configuration

The checker code contains no date constants, no historical paths. Special cases of existing projects are centralized in one onboarding configuration: the exemption list, frozen directories, the repo-wide broken link baseline, rule effective dates, and the work package root directory. New projects don't have this file: no frozen zones, no effective dates, a baseline of zero. The boundary "project history must not enter the checker code" was upheld during review.

Enforcement Points: Not Hooks, Not CI

The project explicitly decided to use neither git hooks nor CI gates — only two enforcement points: a row in the entry file's routing table, and a step in the release sealing checklist. Why does this still count as machine enforcement? The routing table is where agents will definitely read; "run doc-lint after changing documentation" is a standing instruction for every session that edits documentation; release sealing is a gate every version must pass through; and when a hook blocks an agent, the cheapest way out is often to bypass rather than fix the documentation — putting the check into the agent's own workflow means the output directly tells it which line is wrong.

The cost must also be stated clearly: without hooks, whether doc-lint runs depends on the agent reading and following that one line, violations may enter the repository between two sealings, and at the latest they're caught at the next sealing.

How doc-lint differs from general linters: traditional linters (like ESLint, Pylint) target code syntax and style, while doc-lint checks the structural properties of documentation as a "collaboration contract" — stable IDs, glossary values, table header column counts, completeness of metadata keys, broken link counts. It doesn't judge whether a narrative is accurate, only whether machine-parseable conventions are followed. Such tools are typically organized by check code, each corresponding to a reproducible judgment condition, with output deliberately formatted as "one issue per line" so agents can directly locate and fix.

Why the script carries its own unit tests: the checker is itself code and can be wrong — the case in the article where link checking didn't skip code blocks and produced 58 false positives is an example. The 62 unit tests aren't to validate the documents being checked, but to establish a credibility baseline for the checker: when rules are adjusted or new check codes are added, the tests tell maintainers which existing judgments were unintentionally broken. Without tests, one "improvement" could cause the entire repository's error count to explode, and then get bypassed by agents using the exemption list.

Memory Layering and Freshness

Personal memory retains only collaboration preferences; project-level lessons enter L0 or L1 by hierarchy. Before migrating, verify, then move; after moving, check the facts once more. Of the 21 memories migrated during cleanup, 4 were partially outdated — only the parts that still held were moved. More interestingly, verbatim migration carries errors along — the old entry file's claim "dev = production/real data in the user's conceptual model" was itself wrong; after being verbatim-migrated into the newly written development environment documentation, it was caught during review, corrected by the user, and the repository and personal memory were corrected together.

Current-fact documents (project overviews, roadmaps, various specs) most fear being "once correct, now wrong." The rule is that the header must carry Last reviewed: YYYY-MM-DD — missing is an error; a review date earlier than the most recent release means the last confirmation was before the previous version. Regular checks only warn; in sealing mode, an outdated project overview or roadmap is an outright error. The roadmap top keeps at most 5 banners, with earlier ones moved to the archive, and the plan index allows none — banners record "what recently happened," and a cap is what makes them roll.

Two media of agent memory: personal memory usually refers to user preferences or summaries persisted across sessions (injected by the platform between sessions), while project-level memory is files in the repository readable by any session (like AGENTS.md, specs, roadmaps). The two rot differently: personal memory easily retains outdated conclusions, while project files easily become "once correct, now wrong." The Last reviewed: YYYY-MM-DD in the article is a freshness stamp for the latter, in line with the "content freshness date" concept in documentation engineering — by that date, either confirm or rewrite, otherwise it's considered invalid.

Why verbatim migration carries errors: the old entry file's claim "dev = production/real data in the user's conceptual model" was a semantic error, but it was written in an authoritative position and treated as an existing fact. Verbatim migration doesn't distinguish "original wording" from "whether the original assertion holds," so the error travels with the text into the new document and gains the new document's authority. The correct approach is first to independently verify the assertion (in this case done by review + user correction), then decide whether to keep, fix, or discard.

Where Humans Adjudicate

Principle Two's second half is fully recorded in the cleanup: approve the plan (the code in the plan had been rehearsed on a repository copy), draw boundaries (move the project history mapping out of the checker code into a one-time migration script and project configuration), correct definitions, reject a false defect (the comment on the save endpoint was narrower than the implementation; the user pointed out that the detail page calls it before clicking "approve," the judgment was withdrawn, and the documentation was changed to "the comment is narrower than the implementation, code takes precedence"), and decide not to do things (not using hooks or CI is a project-level decision).

They share one thing: machines can find inconsistencies but can't judge which side is right.

Cleanup Results: 304 to 0

33 commits, measuring before and after with the same ruler. doc-lint violations dropped from 304 ERRORs to 0; the entry file AGENTS.md went from 457 lines to 242; repo-wide broken links were 521 both before and after (entry layer was 0 both times) — all 521 entered the ratchet-only baseline.

Link checking also produced a reverse case: using the old pre-cleanup checker on the post-cleanup tree yielded 638 — more than before the cleanup. This was a false positive — the old checker treated example links inside code blocks as broken links, and the post-cleanup documentation had more examples. The cleanup itself also exposed problems: migration scripts are code and must be run on real data first (308 ERRORs before rehearsal, 0 after); one-time migration scripts cannot be re-run, and this must be written into the documentation — otherwise the next agent will re-run it because the documentation says so.

Four Fractures in the Mechanism Itself

The checker itself can be wrong. Link checking initially didn't skip code blocks, producing 58 false positives just from the cleanup plan's own example links, plus another 12 from existing documentation. Rules can also expire — glossary, column counts, and length limits are set by current practice; when practice changes but rules don't, agents distort documentation to satisfy outdated rules. The countermeasure is to list the checking rules in tabular form in the document model spec, one-to-one with check codes, and when a rule forces documentation to deform, hand the rule change to a human.

Over-enforcement drives agents to take detours. Rules that can't be satisfied will be satisfied by agents in the cheapest way: writing boilerplate in required sections, filling fields with formally valid values, adding files to the exemption list. So enforcement must come with an exception path, and exceptions must be "explicit, centralized in one place, and visible."

"Ratchet-only" is currently only on paper. Broken links have a numerical baseline — exceeding it is an error; the exemption list has none. Template exemptions were trimmed from 315 to 314 during cleanup, then grew to 318 when merging the main branch due to 4 additions from existing documentation. This increase was justified, but even if it weren't, no check would report an error. The second half of Principle Three currently depends on someone reading the diff — this is the softest link in the mechanism.

A banned-words list leaks itself. This actually happened in the repository where this series was written: while writing the plan, the entire sanitized word list and real configuration names were committed as test fixtures. The handling was to keep the word list only in a non-committed directory, concatenate test fixtures at runtime, add a repo-wide scan to the checker (including commit message scanning), and rebuild the repository history. The lesson: the list of words that must not appear is itself sensitive information, and the checker's configuration is also documentation with its own lifecycle.

The checker also needs its own lifecycle: the four fractures mentioned in the article all point to the same blind spot — rules, exemption lists, banned-word lists, and the checker code itself are also "documentation" that rots, and they usually have no corresponding checker. So "the rules of rules" must exist explicitly: checking rules listed in tabular form one-to-one with check codes, a centralized visible audit for the exemption list, the banned-word list not committed with the repository, and no date constants or historical paths in the checker code (history goes into one-time migration scripts and project configuration). This boundary was upheld through code review, once again confirming Principle Two — machines enforce judgeable conventions, humans adjudicate the parts that can't be judged.

Core Conclusions

Documentation rots in three places: work done without write-back, conventions dependent on self-discipline, old facts refusing to exit. Written rules can't stop it, because the agent writing documentation is equally forgetful. The solution is three principles plus a set of mechanisms: write-back is part of the change, machines enforce conventions while humans only adjudicate, zero tolerance at the entry and ratchet-only at deeper levels. Every rule sits on the enforcement ladder, and the question to ask is "can it climb one more level?" \ nIn this system, humans are no longer readers and maintainers — they are adjudicators.