papercuts

name	papercuts
description	Record, inspect, triage, and resolve avoidable recurring friction with the papercuts CLI. Use after recovering from misleading tooling, broken documentation, confusing conventions, missing helpers, or repeatable workflow dead ends; and when asked to review, query, group, or resolve recorded papercuts. Do not use for ordinary implementation bugs or expected exploratory failures.

Papercuts

Keep reporting lightweight and subordinate to the user's task. Recover first, then record only friction that is avoidable and likely to recur.

Record Friction

Confirm the CLI is available:

command -v papercuts

If it is unavailable, say so briefly instead of installing software without authorization.

Record a papercut after recovering:

papercuts add \
  --kind tooling \
  --context "discovering nearby Go CLIs" \
  --workaround "used find instead of an unmatched zsh glob" \
  "zsh rejected the unmatched repository glob before the command ran"

Choose a short category such as tooling, docs, workflow, environment, or api. Include:

• A specific, standalone summary.
• The activity that exposed the friction.
• The successful workaround or recovery path.

Never include secrets, credentials, sensitive customer data, or large raw tool output.

Do not record:

• The implementation bug the user asked to fix.
• Expected negative tests or deliberate exploratory probes.
• A one-off typo with no misleading affordance.
• A transient external failure without a repeatable local improvement.

Inspect And Triage

Use the typed commands for common workflows:

papercuts list
papercuts list --repo . --status open
papercuts --json list --status all
papercuts schema

Use read-only SQL for grouping and investigation:

papercuts sql 'SELECT repo, kind, count(*) AS occurrences FROM papercuts WHERE status = "open" GROUP BY repo, kind ORDER BY occurrences DESC'

Prefer recurring clusters with a clear, small remediation. Do not automatically create issues or mutate external systems unless the user asks.

Resolve Reports

Resolve a report only after verifying that the underlying friction was addressed:

papercuts resolve 1 --resolution "quoted optional globs in the repository discovery helper"

Keep the resolution concrete enough that another agent can understand what changed.