| # Docs Drift Collector |
|
|
| ## Objective |
|
|
| Find places where documentation has drifted from code, tests, CLI behavior, API schemas, screenshots, or examples, then propose small verified patches. |
|
|
| ## Trigger |
|
|
| - Schedule: weekly for active repositories. |
| - Event: release branch cut, public API change, CLI flag change, docs-related issue, or failed docs example. |
| - Manual bootstrap/debug command: "scan for docs drift around this feature." |
|
|
| ## Intake |
|
|
| - Changed files since the last release. |
| - Public docs, README sections, examples, generated API references, CLI help, OpenAPI specs, and tutorials. |
| - User reports or search queries that indicate confusion. |
|
|
| ## Agents |
|
|
| - Explorer: maps changed behavior to docs that mention it. |
| - Implementer: patches docs, examples, or comments. |
| - Verifier: runs docs tests, examples, link checks, or CLI help comparisons. |
| - Reviewer: checks tone, accuracy, and scope. |
|
|
| ## Workspace And Permissions |
|
|
| - Use a docs-focused branch or worktree. |
| - Allow docs, examples, comments, and tests that verify examples. |
| - Require approval before changing product behavior, public API, or generated docs sources. |
|
|
| ## Durable State |
|
|
| - Candidate drift items, checked files, accepted patches, rejected false positives, and verification commands. |
|
|
| ## Loop Steps |
|
|
| 1. Identify recent behavior changes or stale-doc signals. |
| 1. Delegate mapping, patching, verification, and review to separate roles when the drift set is large. |
| 1. Search docs for old names, flags, endpoints, screenshots, or examples. |
| 1. Compare docs against code, schema, tests, or runtime output. |
| 1. Patch only confirmed drift. |
| 1. Run docs checks, examples, and link verification. |
| 1. Record false positives so the next loop does not repeat them. |
|
|
| ## Verification Gates |
|
|
| - Updated examples run or match current CLI/API output. |
| - Link checker passes. |
| - No generated file is edited manually unless that is the project convention. |
| - Diff is scoped to confirmed drift. |
|
|
| ## Budget And Exit |
|
|
| - Max retries: 2 per drift item. |
| - Max runtime: 60 minutes. |
| - Stop when all high-confidence drift items are patched, remaining items need owner judgment, or verification cannot run. |
|
|
| ## Escalation |
|
|
| Escalate when docs conflict with product decisions, generated docs are out of date, examples require credentials, or screenshots need design approval. |
|
|
| ## Loop Instruction |
|
|
| ```text |
| Scan for documentation drift related to <feature, release, or changed files>. |
| Confirm each drift item against code, tests, schema, or runtime output before editing. |
| Patch only verified mismatches, run docs/link/example checks, and record false positives. |
| ``` |
|
|
| Example automation: run weekly, or trigger after a release branch, API schema change, CLI flag change, or docs-related issue. |
|
|
| ## Failure Modes |
|
|
| - Updating docs based on guesswork instead of runtime evidence. |
| - Editing generated files directly. |
| - Changing examples without running them. |
| - Treating missing docs as drift when it is really a product documentation decision. |
|
|
| ## References |
|
|
| - [Run prompts on a schedule](https://code.claude.com/docs/en/scheduled-tasks) - Documents recurring prompts, monitors, reminders, and scheduled checks. |
| - [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide) - Shows how lifecycle hooks can enforce deterministic checks around agent work. |
|
|
