papercut-review

---
name: papercut-review
description: Analyze, triage, fix, and lifecycle-manage a papercuts corpus (the local friction-capture CLI). Use this whenever the user mentions papercuts in the context of reviewing, analyzing, triaging, prioritizing, fixing, addressing, resolving, or reopening them — "review my papercuts", "what's hurting", "papercut report", "what should I fix first", "address that papercut", "did that fix stick" — and whenever the user has just run `papercuts stats/list/export` and wants insight, or asks whether recorded friction has actually been fixed. Also use it when the user wants to mark papercuts resolved or bring one back: the lifecycle rules here (resolve only after a verified fix; reopen = regression) are part of the skill, not obvious from the CLI.
---

# Papercut Review

Papercuts capture friction. Capture alone fixes nothing — an unreviewed corpus
is a write-only diary. This skill closes the loop: **snapshot → cluster →
rank → skeptically verify → fix → resolve**, ending in a report with the
tables that make pain visible and a lifecycle state that stays trustworthy.

Three principles govern everything below:

0. **Requested scope is the deliverable.** A review request is not a fix
   mandate; "fix the worst papercut" is not a mandate to also fix the
   second-worst. When the analysis surfaces adjacent verified-fixable
   clusters, **propose** them in the report's recommendations — with the
   evidence that makes them cheap to approve — and stop there. The corpus
   owner is prioritizing with their own budget; unprompted scope expansion
   spends it for them and muddies attribution of changes. The same rule
   governs lifecycle: resolve only records covered by the user's ask *and*
   a fix you landed and verified inside that ask.

1. **Volume is the pain signal.** Papercuts are deliberately recorded on
   *every* encounter, including repeats. Never dedupe records away during
   analysis — nine records of one gate false-positive in a day is not noise,
   it is the strongest prioritization evidence in the corpus. Count them,
   don't collapse them.
2. **A papercut's diagnosis is a hypothesis, not a fact.** Records are written
   mid-frustration, often by an agent that just got burned. The observation
   ("output was mangled") is usually reliable; the attributed cause ("a
   redaction hook mangled it") frequently is not. Verify before you fix, and
   verify before you report.

## Phase 0 — Snapshot the corpus

Establish ground truth before interpreting anything:

```bash
papercuts stats --repo all            # totals, by-day, by-source, by-repo
papercuts stats --repo all --include-resolved   # compare: resolved delta
papercuts list --repo all --limit 1000 --json > corpus.json
```

If `bun` is available, `scripts/snapshot.ts` (bundled with this skill) turns
`corpus.json` into the working views; otherwise build them with whatever
runtime is at hand:

- **compact view** — one line per record, chronologically indexed:
  `#idx [date] [repo] [source] body…`. Every later claim cites `#idx`.
- the by-repo / by-day / by-source count tables.

Note the resolved-vs-active delta. A corpus where nothing has ever been
resolved tells you the loop has never closed — say so in the report; it is a
finding, not a footnote.

## Phase 1 — Cluster into recurrence signatures

Category tags and repo names are weak groupings. Cluster by **failure
signature**: the underlying mechanism, expressed as a pattern over record
bodies (e.g. "shell variable clobbers PATH", "gate denies read-only command",
"output silently truncated"). Grep the compact view; iterate the patterns
until the big clusters are clean.

For each signature compute three numbers — together they distinguish
environmental problems from one-off stumbles:

- **count** — total records (remember: volume = pain, repeats count)
- **day-span** — distinct days, first → last occurrence
- **repo-spread** — distinct repositories

A signature with high count across many days and repos is *environmental*
(the tooling, the shell, a global config) and fixing it pays everywhere. High
count in one repo on one day is usually a single bad session or one broken
gate — cheap to fix, but verify it isn't already fixed before proposing work.

## Phase 2 — Split false-evidence from friction, then rank

Classify every major signature into one of two severity classes:

- **False evidence**: the tool returned a *plausible, confident, wrong
  answer* — exit 0, no error, output that reads as real. Silent flag
  misparses that rewrite output, empty results that compare equal to empty
  expectations, silently-capped listings, defaults that hide data. These
  corrupt conclusions and decisions made downstream.
- **Friction**: cost time, retries, or annoyance, but failed *visibly*.

**False evidence outranks friction regardless of count.** A 3-record
false-evidence signature that fed a wrong audit conclusion matters more than
a 20-record papercut about noisy logs. Within each class, rank by
count × day-span × repo-spread, weighted toward recency.

When the user delegates the pick ("fix the worst one"), the ranking is a
judgment call between defensible candidates — highest-volume friction vs. a
smaller false-evidence signature. Make one pick, and **state in the report
which criterion decided it and what the runner-up was**, so the owner can
see the tradeoff and redirect cheaply if they weight it differently.

## Phase 3 — The skeptic pass (required before fixing or reporting)

This is the step that keeps the loop honest, and it applies at two levels.

### 3a. Skeptic-verify each papercut you intend to act on

Before treating a record's stated cause as the thing to fix:

- **Read the actual artifact it blames.** If it blames a hook, gate, or
  config — open that file. Does the blamed mechanism exist at all? Does it
  behave as claimed?
- **Reproduce the failure** with the original (or equivalent) command, in a
  way that cannot cause damage. A reproduction converts hypothesis to fact.
- **Grep the corpus for the same signature under a different diagnosis.**
  Earlier records often contain the *correct* root cause for the symptom a
  later record misattributes. The motivating case: a corpus held the correct
  diagnosis of an `rg -r` flag collision (output silently rewritten to the
  replacement string) for two weeks while three newer records blamed a
  "redaction hook" that did not exist — and the reviewing agent then
  reproduced the same flag collision itself mid-review. The corpus knew; the
  sessions didn't. When this happens, the fix must include **propagation**
  (see Phase 4), not just a patch.

### 3b. Skeptic-review your own review before shipping it

You are as capable of a confident wrong conclusion as any tool. Before the
report or any `resolve` goes out, adversarially re-check it — and **scale the
pass to the stakes**. Anything that ends in a `resolve`, a landed fix, or a
shareable report gets the full pass (as a dispatched independent subagent if
the harness supports one). A quick informational question gets the checklist
applied inline — the pass exists to catch wrong conclusions, not to make
every task maximally expensive. The checklist:

- Are the counts reproducible from `corpus.json` (not from memory)?
- Does every named finding cite record indices that actually say what you
  claim they say? Spot-check by re-reading the raw bodies.
- For every "root cause" you assert: did you reproduce it, read the blamed
  code, or find corroborating records — or are you pattern-matching?
- Did you check whether a "new" finding is already diagnosed, or already
  *fixed*, elsewhere in the corpus or the codebase?
- Is anything in the report an artifact of your own tooling mistakes? (Run
  your greps twice; the tools that generated the corpus's false-evidence
  class are the same tools you are using now.)

Downgrade or drop any claim that fails. Report verified claims plainly and
unverified ones explicitly as hypotheses.

## Phase 4 — Address a papercut

Fix at the root, with the smallest change, at the layer that is actually
loaded:

- **Prefer fixing the tool/gate/template over training the human or agent.**
  A gate that false-positives on read-only commands gets a flag-aware
  matcher; a doc telling everyone to be careful gets forgotten.
- **Prefer the always-loaded layer** — a global instructions file, a hook, a
  scaffold template — over documentation nobody re-reads. If the corpus
  proved a correct diagnosis failed to propagate (3a), the fix *is*
  propagation: put the lesson where every future session sees it.
- **Look for the fix pattern nearby.** Inherited codebases often contain the
  same lesson already learned in an adjacent rule (e.g. a DDL gate that
  exempts read-only text tools, twenty lines below a file gate that doesn't).
  Back-port it rather than inventing a new mechanism.
- **Verify with the original failing command.** The papercut's own text
  usually contains the reproduction. Run it (or its test-suite equivalent)
  after the fix. If the target has a gate/hook test suite, add the papercut's
  case to it — must-allow cases are as load-bearing as must-deny.
- **Probe the other direction before declaring victory.** When you loosen an
  over-broad gate/matcher/check, prove the things it exists to stop are
  *still stopped* — including compound and indirect forms (`cd x && bad-cmd`,
  env-prefixed, absolute paths, `git -C path …`). Narrowing a matcher is the
  classic way to open a bypass, and a fix that trades a false positive for a
  silent hole is strictly worse than the papercut it resolved. Encode these
  probes as new deny cases in the suite, not just a one-off check.

## Phase 5 — Lifecycle

- **A pure review applies no lifecycle changes.** If the task was analysis
  ("review my papercuts", "what's hurting"), the report *proposes*
  resolutions — listing exactly which records a given landed fix would
  close — and touches nothing. Resolving is the corpus owner's lever unless
  they asked you to pull it (a fix mandate, "clean up those records",
  lifecycle management).
- `papercuts resolve <id>` — **only after the fix is verified**, and then for
  **every** record that fix addresses *within the asked scope*, not just the
  newest. Partial resolution leaves the signature looking half-alive;
  resolution beyond the ask is scope creep (see principle 0).
- Leave open any record that *looks* related but has a different root cause —
  and say in the report why it stayed open.
- `papercuts reopen <id>` — when a resolved cut recurs. A reopen is a
  **regression signal**: the fix didn't hold (or got reverted). Treat it as
  such, don't just re-resolve it.
- Never resolve as housekeeping. "Stopped recurring because the project
  ended" and "fixed" are indistinguishable in an unresolved corpus —
  resolution-after-verified-fix is exactly what makes the data trustworthy.
  If the user asks to bulk-clear stale records, push back once with this
  reasoning, then do what they decide.

## The report

Every review ends in a report. Follow the exact structure and table formats in
`references/report-format.md` (read it before writing). Non-negotiables:

- the **corpus overview table** (per-repo: records, active, resolved, span,
  top signature)
- the **signature table** (count / day-span / repo-spread / first→last /
  class / status)
- a **false-evidence section** listing each plausible-wrong-answer case
- **fixes applied**, each with its verification evidence
- **resolutions**: how many records, against which fix, with IDs — plus what
  was deliberately left open and why
- **skeptic-pass outcome**: what was verified, what was downgraded, anything
  refuted

Cite record indices (`#idx`) throughout so every claim is checkable.

• SKILL.md 12 KB
• references/report-format.md 4 KB
• scripts/snapshot.ts 7 KB