What can go wrong with this loop?

False positives when docs live in an unexpected place — teach it where docs are Re-reports won't-fix gaps forever without an acknowledged list Hallucinated 'fixes' if allowed to write conceptual docs unsupervised — keep it mechanical

Doc Drift Detector

Compares the codebase to its docs on a schedule and reports where they've drifted apart — undocumented APIs, stale examples, dead links

L3 · Maintenance Poller Low risk Supervised Fixed interval tested

What it does

Keep documentation honest by catching the gap between what the code does and what the docs claim, before users hit it.

Stops when

continuous

Runs

Fixed interval (0 6 * * 1) · Supervised

How one iteration works

discover → plan → execute → verify → escalate

1
Discover
Enumerate public surface (exported APIs, endpoints, config, CLI flags) and the docs that should cover them.
2
Plan
Match each surface element to its doc; list the mismatches — undocumented, removed-but-documented, or example/signature drift.
3
Execute
Write a drift report; optionally draft the doc patch for clear-cut cases (a renamed param, a dead link).
4
Verify
Confirm a 'gap' is real by re-reading the source — don't flag something that's documented under a different name or page.
5
Escalate
Conceptual gaps (a whole feature undocumented) go to humans; only mechanical fixes are auto-drafted.

The prompt

The tool-agnostic spec the loop runs each pass — copy it, then wire it to your tool below.

Compare the codebase to its documentation. Enumerate the public surface — exported functions/types, HTTP endpoints, config options, CLI flags — and find the doc that covers each. Report three kinds of drift: (1) undocumented surface, (2) documented things that no longer exist, (3) examples or signatures that no longer match the code. Before listing a gap, re-read the source to confirm it isn't documented elsewhere or under an alias, and skip anything on the acknowledged-gaps list. For purely mechanical mismatches (renamed param, dead link, changed signature) you may draft a doc patch as a PR. Leave conceptual gaps for a human. If nothing drifted, say so.

Claude Code

/schedule mondays 6am: run the doc-drift report

Generic

agent -p 'enumerate public surface, match to docs, report drift, skip acknowledged.md, draft mechanical fixes only'

Memory contract

A drift-report.md that's regenerated each run; a small 'acknowledged' list of known/won't-fix gaps so they aren't re-reported.

Verification & guardrails

How it checks itself. Each reported gap is re-checked against source to rule out false positives (documented elsewhere / under an alias) before it lands in the report.

Read-only by default; any doc edits are draft PRs a human reviews
Respects an 'acknowledged gaps' list so known omissions don't spam the report
Only auto-drafts mechanical fixes (renames, dead links), never invents conceptual docs

Failure modes

False positives when docs live in an unexpected place — teach it where docs are
Re-reports won't-fix gaps forever without an acknowledged list
Hallucinated 'fixes' if allowed to write conceptual docs unsupervised — keep it mechanical

Variations

OpenAPI-driven. For APIs, diff the generated OpenAPI spec against the published reference docs for precise endpoint/param drift.
Changelog-aware. Trigger right after a release and focus on surface that changed in that version.

Example run

3 drift items: `createClient(opts)` gained a `timeout` param (undocumented); `/v1/legacy` still documented but removed in 2.0; quickstart example uses old import path. Drafted PR for the dead endpoint + import path; flagged the new param for you. 2 acknowledged gaps skipped.