# Checklist Pruning — audit-cadence removal

Runs after Merge and Persist Findings (step 5), before custom phases.
This is the subtractive half of the checklist learning loop: debrief's
`checklist-feedback` phase only ever ADDS checks (by design), so without
audit-cadence pruning the checklist grows until it is noise and the
operator stops reading it. Pruning lives here — periodic, attention-
budgeted review — never in debrief (session-end is already cognitively
loaded).

Hit-rate evidence comes from `.claude/cabinet/checklist-stats.json`
(schema and write protocol: `cabinet/checklist-stats-schema.md`).

## No-op guards (checked in order)

1. **`.claude/cabinet/qa-dimensions.yaml` absent** — the checklist
   engine isn't active. Skip silently.

2. **`.claude/cabinet/checklist-stats.json` absent, or `runs` < 10** —
   not enough signal to argue for removal. Emit one line and stop:

   > checklist-pruning: stats cover N runs (need 10) — not enough
   > signal to prune yet.

## What to do (when both guards pass)

### 1. Build the evidence table

Read both files. For each dimension compute: `fires`, fire rate
(`fires`/`runs`), catch count, `last_fired`, `severity`, and number of
checks. Also detect:

- **Orphan stats entries** — stats dimensions with no matching entry in
  the yaml (usually a rename). Report them; offer to fold the history
  into the renamed dimension or drop it.
- **Dead paths** — dimensions whose `paths` globs match zero files in
  the current repo (`git ls-files`). These can never fire again as
  written.

### 2. Select candidates (evidence classes, not thresholds)

Promotion to candidate is judgment informed by the numbers — there is
no magic cutoff, and thresholds are per-dimension (severity matters):

- **Never fired** — 0 fires across all runs. Paths are dead or too
  narrow. Candidate: fix paths or remove.
- **Fires, never catches** — high fire count (≈10+) with zero recorded
  catches. This is the checklist-fatigue profile. Severity-weight it:
  a `high`-severity security check with this profile may still be
  cheap insurance — present it but say so; an `info`-severity check
  with the same profile is a strong removal candidate.
- **Oversized dimension** — more than ~8 checks in one dimension dilutes
  attention at CP3. Candidate: trim the weakest checks or split.
- **Dead paths** — always a candidate (fix or remove), whatever the
  history says.

**Skip recently-reviewed candidates:** anything with a
`pruning_reviews` verdict in the last 90 days is settled — count them
in one summary line ("N candidates skipped: reviewed recently"), don't
re-litigate.

**Attention budget:** present at most 5 candidates per audit run,
highest-evidence first. If more exist, say how many were held back —
never silently drop.

### 3. Present candidates (one at a time, never batched)

For each candidate, show the evidence and the options:

> **Prune candidate: test-staleness** (severity: moderate)
> Fired 12 of 14 runs, 0 recorded catches. 5 checks. Last fired 2026-06-09.
>
> Options: Remove dimension / Trim specific checks / Fix paths /
> Change severity / Keep (won't re-surface for 90 days)

The human decides every verdict. Nothing is removed, trimmed, or
downgraded without explicit approval.

### 4. Apply approved changes

Mirror the write protocol from `checklist-feedback`:

```bash
cp .claude/cabinet/qa-dimensions.yaml .claude/cabinet/qa-dimensions.yaml.bak
```

Read the file, apply the change, write it back preserving formatting
and comments. **Post-write validation:** re-read and confirm the
top-level `dimensions:` map is present and every remaining dimension
still has `paths`, `severity`, and `checks`; if
`scripts/qa-dimensions-validator.cjs` exists, run it. On any failure,
restore from `.bak` and report.

### 5. Record every verdict

Append each verdict — including "keep" — to `pruning_reviews` in the
stats sidecar (atomic temp + rename, fail-open; see the schema doc).
Recording "keep" is what stops the same candidate from resurfacing at
every audit.

## Constraints

- **Removal always human-approved.** Stats inform; the human decides.
  Never auto-prune, whatever the numbers say.
- **One candidate at a time.** Same rule as checklist-feedback
  proposals.
- **Fail-open on stats.** A missing/corrupt sidecar degrades to the
  guard message, never to a blocked audit.
