What it does

Detects and fixes documentation drift: the gap between what your docs say and what your code actually does. Runs as a 5-phase automated process that finds stale docs, undocumented code, and inaccurate examples, then fixes them.

The pattern

Phase 1: Discovery. Glob all documentation files and source files. Map cross-references: which docs mention which functions, which code comments link to which docs, which README sections describe which modules. Build a reference graph.

Phase 2: Drift detection. Check for four types of drift:

• Undocumented code. New public functions, exported modules, or API endpoints with no corresponding documentation. Detection: scan exports and public interfaces, check if docs reference them.
• Stale docs. Documentation that references deleted code, removed features, or renamed entities. Detection: extract identifiers from docs, verify they exist in the codebase.
• Inaccurate examples. Code samples in docs that do not match actual function signatures, parameter names, or return types. Detection: parse examples, compare against source definitions.
• Structural mismatches. Docs describe an architecture (e.g., "three microservices") that no longer matches reality (now four, or consolidated to two). Detection: compare documented component lists against actual directory/service structure.

Phase 3: Targeted edits. Fix each drift instance while preserving the existing documentation style. Match heading levels, list formatting, and voice. Do not rewrite entire files; patch the specific sections that drifted.

Phase 4: Changelog. Generate a report categorizing all changes by severity: critical (docs say the opposite of what the code does), moderate (missing documentation for new features), low (minor naming mismatches). This report is the PR description or review artifact.

Phase 5: Validation. Grep the codebase for any remaining old references. Run link checks on internal documentation links. Lint markdown files. Confirm that the fixes did not introduce new drift.

Key decisions

Stack-agnostic detection. The drift detection logic works on text patterns and file structure, not language-specific AST parsing. This means it works across Python, TypeScript, Go, Rust, or any other stack without per-language plugins.

Patch, do not rewrite. Rewriting an entire doc file to fix one stale reference destroys git blame history and makes reviews harder. Surgical edits are always preferable.

Headless-compatible. The entire pipeline runs without user interaction. This makes it usable in CI, in scheduled jobs, or as part of an autonomous agent loop.

When to use it

After any significant refactoring, API change, or feature addition. As a scheduled weekly job on active codebases. Before major releases to ensure public-facing docs are accurate. Especially valuable in codebases where documentation is maintained by different people than those writing the code.