audit-documentation-drift

Audit Documentation Drift

Determine whether documentation still describes the system it governs. Treat drift as claim conformance: identify a documentation claim, identify the authoritative evidence governing or implementing it, compare them in the applicable revision/scope, and report only demonstrated disconnects.

Inputs and operating mode

Resolve the audited project/component, documentation surface, revision/branch, and material environment variants from the request. Ask only for missing scope that could change the audit result.

Audit read-only. Do not repair documentation or implementation unless a separate instruction explicitly requests repair after the audit.

Resolve scope and authority

1. Discover only documentation and implementation artifacts capable of establishing the requested claims. Do not inventory every file merely because it exists.
2. Distinguish artifact roles:
   • normative/contract documentation — specifies intended behavior;
   • descriptive documentation — describes current implementation;
   • planning/history — records proposed or past behavior;
   • generated/derived documentation — inherits from a source/generator contract;
   • implementation/tests/configuration — observed behavior evidence, not automatically intent.
3. Record unresolved authority instead of assuming code always wins. An unambiguous normative requirement contradicted by implementation is implementation nonconformance, not documentation drift.

Extract testable claims

Extract claims whose truth can materially affect a user or maintainer:

• supported features and public behavior;
• commands, arguments, APIs, configuration keys/defaults and environment variables;
• architecture responsibilities and data flows;
• setup/operational procedures;
• compatibility/version/platform statements;
• executable examples.

For CLI/config-heavy systems, inspect the framework actually used (for example Typer/Click decorators, parser/schema definitions, Pydantic models, constants) rather than relying on language-specific grep recipes.