papercuts
GitHub用于捕获并管理仓库中可复现、可修复的微小摩擦问题，如配置混淆或脚本错误。通过严格筛选排除环境噪音，记录真实阻碍，并支持去重与解决，以提升后续贡献者体验。
Trigger Scenarios
Install
npx skills add every-app/open-seo --skill papercuts -g -y
SKILL.md
Frontmatter
{
"name": "papercuts",
"metadata": {
"internal": true
},
"description": "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.
Log proactively
-
Search
.agents/PAPERCUTS.mdfor an equivalent entry and avoid duplicates. -
Append one unchecked item under
## Openusing this format:- [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>. -
Keep it to one or two sentences: what got in the way, and the likely repo-side fix. Lead with the friction, not with what you were doing.
-
Continue the original task. Do not expand a papercut into unrelated work.
Use UTC timestamps and a short agent label (codex, claude, human). Add a
PR or task identifier only when it helps future triage.
Review or resolve
Only mine a whole session or do a broad review when the user explicitly asks.
When asked to review the file:
- Re-run the two-question test on every open entry; delete any that fail it (environment/shell/flake noise that slipped in).
- Deduplicate and group related entries.
- Verify each surviving papercut still reproduces.
- Fix the smallest safe, high-leverage entries first.
- Move fixed items to
## Resolved, check them, and append the resolving date or commit. Route real bugs to normal issue/fix work; route recurring review-policy gaps throughmaintain-greptile-rules.
Preserve useful history for genuinely-resolved papercuts; do not delete them merely to make the file shorter. (Noise that never belonged — see step 1 — is different: remove it.)
Version History
- cd6a782 Current 2026-08-20 07:33
