Documentation Drift Review
Review project documentation against the code, configuration, commands, API surface, and shipped behavior to find stale or misleading guidance. Uses the indexed docs and source map to verify examples and references instead of proofreading in isolation, then leaves a prioritized morning report with exact doc locations, source-of-truth evidence, corrected text, owners, and a prevention plan. Use for a weekly docs-health sweep, documentation accuracy review, stale README audit, or finding runbook and API-documentation drift.
Steps
Entry step: inventory. Each step names the specialist role it wants; the full working prompt is expandable.
- Inventory documentation contractsreviewerentry
map docs to the source-of-truth surfaces they claim to describe
Show working prompt
Call `map_repo`, `list_file_issues`, and `search_code` to inventory user/admin/developer docs: README and setup guides, API references, CLI help/examples, configuration/environment-variable docs, architecture/decision docs, runbooks, migration/release guides, and inline examples. Build a traceability matrix mapping each important claim to its source of truth (package script, schema, route, exported symbol, config default, CLI definition, or runtime behavior). Prioritize high-harm docs used during install, deploy, recovery, security, and API integration. Record index coverage, generated docs that should not be hand-edited, and the verification plan in `notes/docs/traceability.md`.
- Verify documented behaviorreviewer
check commands, examples, links, schemas, defaults, and architecture claims
Show working prompt
Verify the high-priority claims against real source. Use `outline_file`/`read_symbol` for definitions and `find_references`/`search_code` for renamed concepts. Compare documented commands to package scripts/CLI help, env vars and defaults to schemas/config readers, API examples to route schemas and status codes, file paths to the workspace, and architecture statements to current dependencies/entrypoints. Run safe documented commands or examples when practical and capture exit codes; otherwise mark them statically verified or not verified. Check internal links and code/file references. For each confirmed drift item record doc file:line, exact stale claim, source-of-truth file:line or command evidence, reader impact, severity, corrected wording, and likely owner. Record true positives, false positives, and verified-current docs in `notes/docs/evidence.md`.
- Write the documentation drift reportreviewer
prioritized corrections and prevention work for morning triage
Show working prompt
Write `documentation-drift-review.md` with `## Verdict`, `## Coverage`, `## Drift findings`, `## Verified current`, `## Not verified`, `## Corrections by owner`, and `## Prevention`. Every finding must cite the doc file:line and source-of-truth evidence, explain the reader harm, and include corrected text or an exact update. Rank broken install/deploy/recovery/security/API guidance above tone or grammar. Distinguish stale docs from missing docs and generated docs. Recommend durable prevention such as tested snippets, generated reference sections, link checks, or ownership near source—only where it addresses an observed class of drift. On a loop-back, repair only named gaps.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Grade `documentation-drift-review.md`: (1) high-harm doc classes are covered; (2) every drift finding cites doc file:line plus source-of-truth file:line or command evidence; (3) commands, examples, links, API/config/default claims, and architecture references were checked where relevant; (4) findings include reader impact and exact corrected text; (5) stale, missing, generated, verified-current, and not-verified docs are distinguished; (6) ownership and priority are actionable; (7) prevention recommendations address observed drift patterns. PASS all or loop back. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.
Triggers
Phrases that suggest this craftbook to a crew.
- documentation drift review
- find stale docs
- weekly docs review
- check docs against code
- audit the readme and runbooks
- nightly documentation sweep
Toolsets
- [object Object]
- [object Object]
Source
View this craftbook on GitHub · MIT license