Runbook: Detecting & Resolving Stale Views
This operational runbook explains how to diagnose, identify, and resolve stale derived views when canonical documentation or code sources are updated.
Symptom
CI reports a drift warning or scripts/validate_docs.py fails with:
FAIL — 1 violation(s) (1 stale):
- docs/generated/recruiter/project-overview.mdx: STALE — hash mismatch for
docs/source/architecture/system-overview.md
recorded sha256:4f8a...
actual sha256:7b2e...
Diagnosis Procedure
Run the drift detection script in full scan mode:
python3 scripts/detect_changes.py --all
Review the printed regeneration plan in impact.json. It will indicate which canonical file changed and which contract-target pairs require regeneration:
{
"stale_generated": [
{
"id": "recruiter-project-overview",
"path": "docs/generated/recruiter/project-overview.mdx",
"contract": "GenerateRecruiterPage"
}
]
}
Remediation Procedure
Execute targeted regeneration using the command suggested in impact.json:
python3 scripts/generate_page.py \
--contract GenerateRecruiterPage \
--target architecture-system-overview
After regeneration, verify that provenance hashes match on disk:
python3 scripts/validate_docs.py
Commit the regenerated artifact in a pull request. Once merged, the staleness warning is resolved.