Documentation Verification
Check documented claims against the code, never the code against the document
A semantic contract: vocabulary your project supplies itself — ready to drop into your CLAUDE.md / AGENTS.md.
- Ask what implementation revealed that the documents do not yet say
- For each structural claim in the architecture and specification documents, confirm that it holds today: module names, class names, file paths, table and column names, enum values, invariants, start commands, and claims of the form "the only place where X happens"
- List every claim that no longer holds, with document location and code location
- Never change the code to match the document. The document states an intention, the code states reality. Correct the document, or open an issue where the code is wrong
- Report how many claims were checked and how many had drifted
- Make structural claims mechanically verifiable where the project allows it: table names, column names, module paths, enum values. Traceability tooling that only runs forward (every rule has a test) never notices a documented column the schema does not have
- A structural claim that no test can verify does not belong in the documentation. Either make it verifiable or delete it
- Run the verification again after the bug-fix loop, before release: fixes change behaviour, and changed behaviour is what makes a correct claim stale
Verify the documentation against the code, in both directions.