audit-derivability

Pre-computed context

Current branch: !git branch --show-current 2>/dev/null || echo "unknown" Uncommitted .md files (first 20; empty = none matched or the probe returned nothing): !bash "${CLAUDE_SKILL_DIR}/scripts/uncommitted-md.sh" 20 2>/dev/null || echo "(status unavailable)"

Purpose

Docs carry a standing tax: every tracked document must be kept true as the code it describes moves, and every low-signal document a reader (human or agent) wades through costs attention. A document earns that tax only when it holds something a reader could NOT cheaply reconstruct for themselves. This skill audits one axis the siblings do not: document-level worth. Should this whole document exist at all?

The test is derivability: could a fresh agent reach this document's conclusions by natively exploring the repository, reading the code, config, metadata, and structure, without being handed the document? A document that only restates what the code already says is a derivation cache at best and dead weight at worst; a document that records why a decision was made, a constraint that is not visible in any single file, or a fact that lives outside the repo owns something exploration can never recover.

Read-only classifier: it surfaces a verdict per document with the reasoning; the author owns every deletion and rewrite. Deletion is the highest-stakes doc edit, so, like the sibling /docs-hygiene:audit-noise, this skill never applies it.

The rubric. Four factors, never derivability alone

A verdict is never "derivable, therefore delete." Derivability is one factor of four; weigh all four together. context/rubric.md holds the scoring detail this file only summarizes: factor definitions, the Diataxis fact-ownership mapping, the audience cost model, the spot-test protocol, and worked examples. Load it when a verdict is close.

Factor	Question	Pushes toward
Derivable?	Could a fresh agent reconstruct these conclusions from native exploration alone?	derivable → delete/pointer; not derivable → keep
Re-derivation cost	If deleted, how expensive is it for the next reader to rebuild, a 2-second grep, or a multi-file investigation?	cheap → delete; expensive → keep-as-cache
Drift risk	How fast does the source move underneath this document, and how silently does the doc rot when it does?	high drift → delete/pointer; low drift → cache is safer
Fact ownership	Does the document OWN non-derivable facts. Rationale, decisions, constraints, external facts, cross-cutting invariants no single file states?	owns facts → keep, regardless of derivability of the rest