Documentation that keeps itself current: the agent proposes, your team approves

Documentation goes stale for a boring reason: the code changed and updating the docs was nobody's job. The README describes last year's setup. The runbook has a step that no longer exists. The architecture decision record was accurate on the day it was written and never touched again. Engineers stop trusting the docs, knowledge moves into tickets and chat threads and one person's memory, and every change gets slower to review and harder to operate.

The code stays the source of truth. The problem is keeping everything that describes the code honest about it — and that is a job an agent can hold, as long as a person keeps the last word.

The shape that works

Treat documentation as a system with inputs, outputs, and a gate, and give an agent the loop:

• Detect drift. Compare the docs against what actually changed: the code, the API spec, the configuration, the pull requests merged this week. A doc that references a flag that was removed is drift; so is a runbook whose commands no longer match the deploy script.
• Draft the update. READMEs, runbooks, onboarding guides, integration docs, architecture decision records. The draft cites what it was derived from — the commit, the spec, the diff — so a reviewer can check the source instead of trusting the prose.
• Write the release notes from the commits. Change summaries tied to the tickets and pull requests that produced them, not reconstructed from memory on release day.
• Run the checks. Documentation builds, link checks, linters, and whatever tests exercise the examples — in CI, before a human sees the draft.
• Open a pull request. With the proposed changes, the sources used, and a short review checklist. The agent proposes; the team approves, rejects, or comments; every change is traceable to a review.

That last step is the whole design. Nothing reaches the main branch without a person reading it, which means the docs can be aggressive about catching drift without ever being wrong in production.

The same loop, beyond docs

Once the agent can read the repo, see what changed, and open a reviewable pull request with evidence, documentation is the first of several maintenance jobs it can hold:

• Dependency upgrades that stay reviewable. A proposed upgrade with the changelog summarised, the affected call sites listed, and the test run attached — so a reviewer understands the impact before merging.
• Bug reports that arrive reproducible. A minimal reproduction, a failing test that captures it, a proposed fix, and the runbook updated if the behaviour changed.
• System inventories that match reality. Which services exist, who owns them, what they depend on — regenerated from what is running rather than from a wiki page.

Each of these has the same property: the agent does the reading and the drafting, the person does the deciding, and the evidence travels with the pull request.

What the agent shouldn't decide

It should not decide what is important. It can tell you a doc drifted; it can't tell you whether that doc matters. It should not write the "why" in an architecture decision record — the rationale, the alternatives considered, the trade-off accepted — because that is judgment, and generated rationale reads plausible and means nothing. It drafts the "what"; a person writes the "why."

And it should not merge. The day the gate comes off for documentation is the day the docs become the agent's opinion of the system instead of the team's.

Where to start

One repository, one document type. Runbooks are usually the best first target: they drift the fastest, the drift is dangerous, and "does this command still work" is a check an agent can run rather than guess. If the pull requests it opens are worth approving for a month, widen the scope. If they aren't, you have learned something about the repository, not about the agent.