RMF-Block: Skill for Claude Code

Doc drift audit

A procedure, not a tool. It needs git, gh and node, nothing specific to one agent. Steps that say fan out run one sub-agent per part in parallel if your tool has sub-agents; otherwise run the same parts one after another in a single session — the instructions and outputs are identical.

The coordinator (you) plans, verifies, decides and integrates. Sub-agents find and edit. Never delegate a judgement call (what to fix, which doc owns a fact).

Run every command from the repo root; $SKILL is this skill's directory — .claude/skills/doc-drift-audit (canonical) or its copy .agents/skills/doc-drift-audit; both work. <scratch> is any working directory outside the repo (a session scratchpad, /tmp/…); keep all audit files there, not in the repo.

Single-session mode (no sub-agents): run each fan-out step part by part yourself, still writing every result to its file and keeping only counts in mind before moving on. Do the A/F verification (step 5) as a separate pass that re-reads the files from disk and doubts the findings — ideally in a fresh session, since the same context that wrote a finding is the worst judge of it.

Progress

Copy this into your notes and tick as you go:

- [ ] 0 base commit + issue(s) to close
- [ ] 1 baseline posted on the issue
- [ ] 2 parts.json
- [ ] 3 facts (optional)
- [ ] 4 audit JSON per part
- [ ] 5 verify-AF.json
- [ ] 6 checklist posted, human approval read back
- [ ] 7 edits committed per group, handoffs collected
- [ ] 8 integrated, verified, after-numbers, audit task archived, PR open

Two rules for every step:

• Precision over recall. A false finding costs a human's attention; a missed one costs nothing until the next audit. An auditor that finds nothing has done a good run.
• A step that didn't run is not a clean step. If a check, review or verifier couldn't run, say so — never report it as passed.

0. Before you start

• There is an issue to close: the open drift-audit issue. If that issue's body names another issue as the audit's definition (here it names this skill; older ones named #129), close that too; otherwise there is just the one.
• Find the issue: gh issue list --label drift-audit --state open — call its number $ISSUE.
• Record the base commit on an up-to-date main: git fetch && git switch -c docs/drift-audit origin/main && BASE=$(git rev-parse HEAD). Every measurement, sub-agent prompt and worktree uses it.
• Register the task the repo's way (here: copy tasks/templates/todo.md and tasks/templates/lessons.md to tasks/active/YYYYMMDD-drift-audit-{todo,lessons}.md, then pnpm tasks:index).
• Name the audit's task doc slug exactly YYYYMMDD-drift-audit (in this repo, scripts/post-merge-reminders.mjs treats that slug as "an audit happened" and resets its count from its archive date).
• Every prompt you give a sub-agent starts with: check git log --oneline -1 is <sha>; stop and report if not. Worktrees and checkouts drift; this check is what stops an agent from working on a stale base.