papercuts

name	papercuts
description	Agent complaint box — log friction (dead-end tools, wrong cwd, flaky commands, misleading docs) instead of silently pushing through. Use when you hit any workflow friction during a task.

Papercuts

When you hit friction during work — a dead-end tool call, a broken link, a misleading doc, a footgun config, a missing helper — file it before moving on:

papercuts add "<what you hit and what would have prevented it>" --tag <area>

Don't stop working; file it and push through. Severity: minor (default) for annoyances, major for time sinks, blocker for hard walls.

Commands

papercuts add [--global] <text> [--tag <area>] [--severity minor|major|blocker]
papercuts list [--global] [--format json|md] [--all]
papercuts resolve [--global] <id-prefix>
papercuts unresolvable [--global] <id-prefix> "<reason it cannot be fixed here>"
papercuts clean [--global]
papercuts schema

Scope

Use the repository's .papercuts.jsonl only for friction rooted in that repository's code, configuration, documentation, or workflow. Keep shell, agent, connector, editor, and other shared tooling issues in the global file at ~/.papercuts.jsonl:

papercuts add --global "<global issue>" --tag tooling

When moving an existing cut to the global file, move its cut record and every matching terminal record (resolve or unresolvable) together. Older files may still contain resolve records; new resolutions remove the cut immediately. Do not copy project-specific cuts into the global file.

Workflow