Engineering
Documentation drift loop
A loop that reads your code and your docs, finds where they've diverged, fixes the clear low-risk drift itself (docs-only, verified, committed, pushed), and reports the ambiguous gaps with exact files and a suggested update.
- Trigger
- Recurring sweep over recent git history and the working tree
- Goal
- Find where code and docs have diverged, and close the gap where it's safe
- Artifact
- Clear low-risk docs fixes committed and pushed · ambiguous gaps reported with exact files and a suggested update
- Handoff
- You decide on the ambiguous gaps it didn't touch
- Tools
- Claude Code · Git · GitHub
Audit the codebase for documentation drift and keep the result actionable.
Start by reading AGENTS.md, PLAN.md, PROGRESS.md, ARCHITECTURE.md, docs/README.md, and the
docs relevant to recently changed areas. Inspect recent git history and the current working
tree before drawing conclusions.
Look for source, test, script, runtime, eval, source-adapter, model-boundary, workflow, or
configuration changes that should have corresponding documentation updates. In particular,
verify that changes affecting modules, source adapters, model/runtime boundaries, workflows,
verification commands, smoke tests, or output contracts are reflected in the appropriate docs
and in PROGRESS.md when they are active or recently completed.
When a missing documentation update is clear and low risk, make the smallest accurate docs
update in the repo and run the relevant lightweight verification for docs formatting if
available. Do not change product code. If docs changes are made and verification passes,
commit the docs-only changes with a concise conventional commit message and merge into main.
Push to origin/main.
When the right documentation change is ambiguous, do not guess. Report the gap with exact
source files, exact docs that appear stale or missing, and a concise suggested update.
Finish with a short summary containing:
- undocumented or stale areas found
- docs updated, committed, and pushed, if any
- verification run
- blockers or follow-up questions
If no drift is found, say that explicitly and include the git range or evidence reviewed.
Use this when
Use this when code moves faster than its docs and you want the obvious drift closed automatically while the judgment calls still come to you, instead of a once-a-quarter docs cleanup nobody schedules.
How to run it
Run it inside the repo with permission to commit and push. Without that access, it stays report-only.
It reads your AGENTS.md, PLAN.md, PROGRESS.md, ARCHITECTURE.md and docs against recent git history and the working tree to find where code and docs have diverged.
Clear, low-risk drift it fixes in place: the smallest accurate docs-only change, run through your docs verification, committed with a conventional message, and pushed to main.
Anything ambiguous it refuses to guess on, reporting the exact source files, the stale docs, and a suggested update for you to decide.
Why it works
Splitting the work by confidence is what makes autonomous docs edits safe: only unambiguous, low-risk, docs-only changes land on their own, each verified and conventionally committed, while everything uncertain stays a report. Product code is never touched, so the blast radius of a wrong call is a doc, not a deploy.
Get the next loops
I add new loops as I run them on real work — with the full prompt, the trigger setup, and what breaks. Drop your email and I'll send the next ones.
No spam. The loops, plus the occasional note on building with AI. Unsubscribe anytime.