Documentation and doc-driven instructions must stay truthful and self-consistent with the underlying code and the document’s structure.
Apply this checklist when writing or editing docs/specs/templates:
Match the real code scope: if a section claims something is “Correct” or “stored in X,” confirm the referenced symbol/function/path actually exists and is used within the stated directory/runtime.
Avoid stale or positional cross-references: don’t say “tables above”/“item 7” when the document is reorganized. Prefer stable anchors like section/table names, or update directional wording whenever content moves.
State claims at the right strength: if a metric only bounds an effect (not isolates it), phrase it as an upper bound / diagnostic rather than an estimate of a specific subsystem.
Keep behavior descriptions aligned: ensure wording about failure modes and side effects matches the implementation (e.g., “fails rather than drops” vs the actual “fails and drops”).
Use concrete evidence when relevant (function names, file paths, or file:line quotes) so a reader or scan tool can verify the claim.
Example pattern (robust cross-reference):
❌ “Cite the tables above by name” (breaks after reordering)
✅ “Cite A/B table and verdict table by name” (survives movement)