Correct Documentation Drift

TL;DR

Do not fix drift by editing the first wrong-looking page. First classify the disagreement, identify the source of truth, decide whether the current system or the documented intent is correct, then update every affected surface in one change.

Drift types

Workflow

1. Capture the mismatch

Write down the two or more conflicting claims. Be concrete:

• Page or file path.
• Claim text or diagram element.
• Source that contradicts it.
• Date or commit where the contradiction appeared, if known.

Avoid vague reports such as "docs are stale." They are not actionable.

2. Classify the surfaces

Mark each surface as one of:

• Generated reference — contracts, schemas, CLI tables, error catalogues.
• Runtime source — code, tests, migrations, deployment config, traces.
• Active guidance — principles, service handbooks, runbooks, active TDD docs.
• Historical record — accepted ADRs, delivered bets, incident records.
• Agent execution — skills and skill evals.

3. Identify the source of truth

Use this order unless the page states a stricter rule:

1. Generated contracts and schemas define public interfaces.
2. Code, migrations, deployment config, and tests define shipped behaviour.
3. Accepted ADRs define historical decisions until superseded.
4. Active bet and TDD docs define current delivery intent before shipping.
5. Principle and service handbook pages define durable guidance.
6. Skills define agent execution behaviour, not durable engineering knowledge.

4. Decide whether to fix code or docs

A mismatch does not always mean the docs are wrong. Ask:

• Did code drift away from an intentional design?
• Did the design change but docs were not updated?
• Did a generated reference fail to regenerate?
• Did a skill preserve old policy after docs changed?
• Did an ADR get superseded without a new ADR?

If the documented design is still correct, fix code or create a delivery task. If shipped behaviour is correct, update active docs and skill references.

5. Update all affected surfaces

A complete drift correction may need changes to:

• Docs page content and last_reviewed metadata.
• Diagrams and data-flow descriptions.
• OpenAPI or AsyncAPI specs.
• Code, tests, migrations, or deployment config.
• ADRs when the decision changed.
• Skill context routing and verification steps.
• llms.txt, llms-full.txt, and Markdown exports.
• Skill-to-doc map entries.

6. Add a regression guard

Choose the cheapest guard that would have caught the drift:

• Health check for version strings, missing frontmatter, or broken links.
• Contract generation check for API/event reference drift.
• Diagram drift check for service-topology claims.
• Test or trace assertion for runtime flow claims.
• Skill eval for agent behaviour drift.
• Review-cadence change for pages that stale quickly.

7. Verify

Run the relevant commands:

./dev docs health
cd services/wordloop-docs && pnpm run docs:health

Run service tests or generation commands when code, contracts, or generated docs changed.

Data-flow and design-doc drift

Data-flow drift is high risk because it misleads implementation and agent planning. Treat these checks as mandatory for active bets and service handbooks:

• Every service boundary in a data-flow diagram has a contract or explicit TODO.
• Every persistent object in a TDD has a schema plan or a reason it is transient.
• Every event shown in a diagram appears in AsyncAPI or is marked proposed.
• Every API operation shown in a guide appears in OpenAPI or is marked proposed.
• Every failure path that crosses a service boundary has an owner and response strategy.
• Every implementation milestone updates active TDD docs when it changes the design.

Hallucination controls

Use these controls when correcting drift with AI assistance:

• Ask the agent to cite local source files, specs, or docs slugs for factual claims.
• Prefer generated contracts and package metadata over prose memory.
• Do not accept newly invented standard names, endpoints, event names, or commands without checking the source.
• Require exact paths for changed files and exact commands for verification.
• Search the repository before introducing new terminology.
• Treat external web claims as untrusted until verified against an official source.

Anti-patterns

• Patch one page and stop. Drift is usually cross-surface.
• Refresh dates without review. A new date on stale claims is worse than an old date.
• Rewrite history. Supersede ADRs and annotate delivered bets instead.
• Trust AI recall. Use source files, contracts, and official references.
• Leave no regression guard. If the drift was expensive, add a check.

Related

• Documentation Freshness
• Keep Docs and Skills in Sync
• Documentation