Run enough AI coding agents against a project long enough and the paperwork around the code starts to rot — what I call 📝paperwork rot: stale task-tracker items nobody removed, duplicate "report" docs nobody reads, changelogs nobody curated. The fix isn't a recurring cleanup chore — it's making cleanup ride the event that made the old state stale, so nothing accumulates in the first place. This is the hygiene policy I run alongside the 📝A Git Protocol for Parallel AI Coding Agents: the core principle is hygiene rides the event, not the clock.
Every artifact that accumulates should shed stale state at the moment of the write that would otherwise bloat it — a task completing, a 📝PR opening, a release shipping. Time-based sweeps are a backstop for what slips through, never the primary mechanism.
Give Every Artifact a Declared Lifecycle
Anything that accumulates over a project's life — a task list, a per-session report, a changelog — should have an explicit answer to four questions: when is it born, how long does it stay relevant, what event ends that relevance, and where does the relevance go when it does.
A few concrete examples from how I run this:
- Session reports. Don't keep a standing "report" document per work session. A session's outcome is one dense log line written at close-out — status, what changed, a link to the PR. It needs no cleanup of its own because it never grows past one line per session.
- In-flight initiatives. Born when work starts; relevant until the end condition is met; the cull trigger is the moment that condition ships. Delete it then, leaving a one-line breadcrumb pointing at the commit/PR that closed it out.
- Task trackers / roadmaps. Persistent, but hold only what's queued and what's in progress — never a "completed" section. An item leaves the tracker the moment it's handed off (a PR opens), because from that point its review and merge state live in the PR, not in a document you have to keep in sync with the PR by hand.
- Change logs. Depend on whether the project has a public audience:
- No public audience → no change log at all. 📝Git is the complete record, and the only readers already have it.
- A staging/internal change log is unnecessary if your PR host tracks open/merged state for you — that is the staging record.
- A public change log is written at release time, derived from the diff, and curated to plain language (see below). Keep only the current period live; roll prior periods into a dated archive so the live page never grows past one page.
- Architecture / operating-context docs are the one exception: they're not accumulating state, they're a standing description of how the thing works right now. Update them in place; retire them only when the project itself is retired or superseded.
The Editorial Cut for a Public Change Log
If you do maintain a public-facing change log, apply a deliberate cut when deriving each entry from a shipped diff:
- Plain, user-benefit language. What changed for the reader — never internal or technical specifics they don't need.
- Omit minor, highly technical, or user-irrelevant changes. They live in Git; they don't need a second home.
- Route security fixes to a vague-positive bucket ("Security & stability improvements"). Never detail a vulnerability or admit prior severity in public — disclosing that a serious bug existed erodes trust for no reader benefit once it's already fixed.
Naming and Supersession
- When one document replaces another, say so. Rename for contrast, record in the old document's notes what replaced it and why, and retire the old term everywhere it appears. Skipping this is cheap in the moment and expensive later — the two-name confusion where nobody can reconstruct which one is canonical is a recurring, entirely avoidable failure mode.
- One concept, one home. Two documents with near-identical names or overlapping scope is a defect to fix immediately, not a coincidence to shrug at.
- One fact, one home, across document types too. A standing description of "how this works" belongs in your architecture/context doc. Standing rules belong in a policy doc like this one. Work-tracking belongs in the roadmap/task tracker. When two document types could plausibly hold the same fact, that split is what decides which one actually should.
- Provenance lives in Git, never in a document. A completed PR number, a commit hash, "shipped on this date" — that's Git's record, not a memo's. When you harvest a durable learning out of a completed task, harvest the fact that's now true (how the thing works, what state it's in) — never the shipping event that made it true. The event lives in the PR, the commit, and (if you keep one) the session log. A standing architecture doc describes current state; it should never accrete a running changelog of its own edits — that's Git, duplicated into a document that never gets cleaned up because nothing ever triggers its cleanup.
- Before retiring anything that other systems point at by ID or URL (a context doc, a changelog, a roadmap), inventory every hardcoded reference to it — config files, scripts, cron jobs, sync bindings — not just the places a redirect would catch. A retired document that nine config files still silently point at is a broken system, not a tidied one.
Enforcement
Hygiene only works if something actually triggers it at the right moment:
- Per session — whatever your close-out step is (a script, a checklist, an agent instruction) should enforce task completion and tracker removal in the same pass as the work itself, not as a separate chore.
- At release — the ship step derives the curated public change-log entry from the diff, and performs the periodic archive rollover when a new period starts.
- Periodically, as a backstop only — a scheduled sweep that trashes anything past its declared retention window, flags orphaned or ambiguous artifacts for a human to look at, and surfaces naming drift. This should find almost nothing if the event-driven triggers above are actually firing. It's a safety net, not the primary janitor.
Deletions should be soft (a trash window, restorable) and narrow in scope — a periodic sweep should never auto-delete anything ambiguous; it flags, a human decides.
Why This Is Worth the Setup Cost
The alternative to event-driven hygiene is a library, wiki, or tracker that only gets cleaned when someone notices it's a mess and blocks time for it — which in practice means it doesn't get cleaned, because "notice and block time" doesn't scale with how fast agents produce artifacts. Tying cleanup to the event that makes an old artifact stale means the system stays legible faster than a human could track it by hand, at close to zero marginal cost per event.