# Papercuts

Log genuine, recurring repository friction to .agents/PAPERCUTS.md, confusing setup, a...

- Repository: https://github.com/every-app/open-seo (25988 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add every-app/open-seo --skill papercuts -g -a claude-code -y`
Codex: `npx skills add every-app/open-seo --skill papercuts -g -a codex -y`
Cursor: `npx skills add every-app/open-seo --skill papercuts -g -a cursor -y`
Gemini CLI: `npx skills add every-app/open-seo --skill papercuts -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add every-app/open-seo`

## 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.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

1. **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.
2. **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 or `fetch 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_modules` after 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

The rest: https://github.com/every-app/open-seo/blob/HEAD/.agents/skills/papercuts/SKILL.md