Documentation Drift Detection

Documentation drifts from reality the moment it is published. The API adds a parameter. The deployment process gains a step. The configuration file changes format. If the documentation is not updated in lockstep with the system, readers encounter outdated instructions that fail silently or produce unexpected results. Drift detection is the discipline of identifying documentation that no longer matches the system it describes.

The drift detection workflow: maintain a mapping between documentation pages and the source artifacts they describe (API specs, configuration files, deployment scripts). When a source artifact changes, flag the mapped documentation for review. Claude can assist by comparing documentation against updated source material: "Compare this documentation page against this updated API spec. List every discrepancy — parameters added, removed, or changed; response formats modified; error codes updated; examples that no longer produce the documented output."

1. 1. Build the Mapping For every documentation page, record which source artifact it describes: API spec file, configuration schema, deployment script, or codebase module. This mapping is the drift detection index.
2. 2. Monitor Source Changes When a source artifact changes (via PR, deploy, or config update), flag all mapped documentation pages for review. Automate this with git hooks or CI pipeline steps where possible.
3. 3. Reconcile and Update Use Claude to compare the flagged documentation against the new source artifact. Generate a diff of required documentation changes. Apply the changes and update the mapping's last-verified timestamp.