---
name: papercuts
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."
metadata:
  internal: true
---

# 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

1. Search `.agents/PAPERCUTS.md` for an equivalent entry and avoid duplicates.
2. Append one unchecked item under `## Open` using this format:

   ```markdown
   - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — <friction, and the smallest useful fix or workaround>.
   ```

3. Keep it to one or two sentences: a current example (command/error or affected
   path), who it blocks or what time it wastes, and the smallest useful repo-side
   fix. Lead with the friction, not with what you were doing.
4. 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.

For a review or prioritization request, inspect and recommend; do not edit the
log or implement fixes unless the user also asks for cleanup or implementation.
Carry out an authorized cleanup using the same triage:

1. Re-run the two-question test on every open entry; recommend removing entries
   that fail it (environment/shell/flake noise that slipped in).
2. Deduplicate and group related entries.
3. Check whether each surviving papercut still reproduces. Distinguish reproduced
   failures, source inspection, and historical reports you could not verify.
4. Prioritize current impact against review and maintenance cost. Prefer an
   existing command or a short documentation fix over new helpers, dependencies,
   or setup hooks. Defer hypothetical improvements until a concrete need appears.
5. For an authorized cleanup, remove noise, consolidate duplicates, and implement
   the agreed fixes. Move fixed items to `## Resolved`, check them, and append the
   resolving date or commit. Keep deferred reports separate from actionable open
   work, with a reason and a concrete trigger to revisit. Route real bugs to
   normal issue/fix work; route recurring
   review-policy gaps through `maintain-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.)