Ugrás a fő tartalomra

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.