Papercuts
Log genuine, recurring repository friction to .agents/PAPERCUTS.md, confusing setup, a...
Install
npx skills add every-app/open-seo --skill papercuts -g -a claude-code -y- Repository
- every-app/open-seo26k
- Category
- AI and agents
- Updated
- 5d ago
- License
- MIT
- Context cost
- Lightabout 1,039 tokens
- Runs scripts
- No, instructions only
What it does
Log genuine, recurring repository friction to .agents/PAPERCUTS.md, confusing setup, a flaky repo command or script, a misleading in-repo error, stale generated files, or a non-obvious gotcha that will cost the next contributor time. Also use to review, deduplicate, and resolve existing entries. Gate hard before logging: only friction the repository itself can fix counts. Never log the agent's own sandbox/permission errors, shell-scripting mistakes, transient flakiness, or third-party tool quirks the repo can't change.
Papercuts
Capture small friction in the moment without derailing the current task. Aggregated entries show where the repository needs sanding down, so the bar is that a different contributor would hit the same thing, and the repository can do something about it.
The two-question test
Log it only if both are true:
- Reproducible for anyone. A different person, on a fresh checkout, working in this repo would hit the same friction. It is not specific to your sandbox, shell config, machine, network, or a one-time hiccup.
- Fixable in the repo. A change to the repo's code, config, scripts, or docs would prevent or reduce it.
If either answer is "no," push through it and move on, do not log it.
Do NOT log
- Your environment's failures. Sandbox
EPERM/listen/ IPC-socket errors, blocked network orfetch failed, permission denials, missing system tools. That is the runner, not the repo. - Your own shell mistakes. Reserved or special variable names (
status,path), unquoted globs, a broken login-shell hook. Fix the command, there is nothing in the repo to sand down. - Transient flakiness. A command that succeeded on retry with no repo-side cause (a network blip, a hung push, a slow mirror).
- Local state you corrupted. A partial
node_modulesafter branch-switching, a stale dev-server port, a dirty cache. Re-run the install or cleanup. - Third-party or beta-tool limitations the repo can't change, unless the fix is a repo-side workaround worth writing down (then log that workaround).
- Product or code correctness bugs (fix now or track as real work), and what you accomplished (that belongs in the task summary).
- Secrets, credentials, personal data, raw customer payloads, or sensitive paths.
When something fails, first ask "is this the repo, or is this me/my environment?" Only the former is a papercut.
