| name | docs-fact-registry |
| description | Use when checking or reporting docs↔code drift — a declarative registry (claim → source of truth → policy) with a three-way classification: mechanical facts auto-fixable, judgment calls escalated, dead references flagged as inconsistencies whose fix is a decision. |
Docs Fact Registry
What this is, and when to invoke it
Docs drift silently, and ad-hoc drift checking produces the two classic failures: facts "verified" against the very doc under check, and judgment calls silently overwritten by an auto-fixer. This skill makes drift-checking declarative — a registry of claims, each with a source of truth and a policy — and keeps the policy attached to the finding all the way to the fix decision.
Invoke when checking or reporting docs↔code drift (the documentation-auditor preloads this skill), or when authoring anything that auto-updates documentation.
The registry (MUST)
Drift is checked against a registry: claim in docs → source of truth in code → policy. The checking agent instantiates the table in-context per run from the docs under review — no checked-in registry file is required (a project MAY check one in; use it if present).
| Claim (in docs) | Source of truth (in code) | Policy |
|---|
| version string in a plugin table row | manifest version field | mechanical |
| "N plugins" count / badge | manifest entry count | mechanical |
| script path cited in a guide | file exists at that path | dead reference |
| "coverage ≥ 80%" aspiration | CI config threshold | decision |
Three-way classification (MUST — not binary)
- mechanical — uniquely derivable fact (version string, script name, file count) → auto-fixable.
- decision — judgment call (aspirational threshold, descriptive prose, "is docs or code the target?") → escalate; never silently overwrite.
- dead reference — docs cite code that no longer exists: mechanically detectable, but the fix (delete the mention vs restore the code) is a decision — never auto-delete doc content.
Findings retain the class end-to-end: each carries **Drift-class:** mechanical | decision | dead-reference and the derived routing field **Fix-policy:** auto | needs-decision (mechanical → auto; decision and dead-reference → needs-decision). Collapsing to the binary at the finding level erases the delete-vs-restore rationale exactly where the user decides. Missing-entry findings (new functionality with no doc — no registry claim to classify) carry Drift-class: decision: authoring new doc content is a judgment call, never an auto-fix.
Rules (MUST)
- Path vs line. An unambiguously moved file path is mechanical; a cited line number always escalates — it shifts under every edit.
- Numbers from sources, never from the doc under check. Recompute via the checking agent's available tools: Glob result counts, manifest field reads. A count copied from the doc "verifies" its own drift.
Anti-patterns
- Self-referential verification — checking a claim against the doc that makes it.
- Auto-deleting doc content because its referent vanished — the mention may be the only surviving record of intent.
- Auto-editing an aspiration to match reality — that silently lowers the bar instead of flagging the miss.
- Transcribing an enumeration between docs — the duplicate is a second drift site; cite by pointer.
- Dropping the class before the fix decision — routing on the binary alone forfeits the delete-vs-restore context.
Worked example (Prospective)
(Prospective: genericized from the source pattern.) Registry excerpt for one run: (1) README says plugin version 1.4.0, manifest says 1.4.1 → mechanical → Fix-policy: auto. (2) Guide cites scripts/install.sh; Glob finds no such file → dead reference → Fix-policy: needs-decision (delete the mention, or restore the script?). (3) README promises "responses under 100 ms"; no source of truth in code → decision → Fix-policy: needs-decision.
Review checklist
Paste into any docs-drift checker review:
