From 016d8396e3f94cf65fffcef3ae1ce9763b7087ef Mon Sep 17 00:00:00 2001 From: Ben Senescu <44480372+bensenescu@users.noreply.github.com> Date: Tue, 14 Jul 2026 21:13:22 -0400 Subject: [PATCH] chore(papercuts): prune environment noise + tighten the skill (#389) --- .agents/PAPERCUTS.md | 23 ++++----- .agents/skills/papercuts/SKILL.md | 70 +++++++++++++++++++-------- .claude/skills/papercuts/SKILL.md | 79 +++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+), 33 deletions(-) create mode 100644 .claude/skills/papercuts/SKILL.md diff --git a/.agents/PAPERCUTS.md b/.agents/PAPERCUTS.md index a17704f..5d7ecb3 100644 --- a/.agents/PAPERCUTS.md +++ b/.agents/PAPERCUTS.md @@ -1,23 +1,18 @@ # Papercuts -Small, non-blocking friction encountered while working in this repository. Log it in the moment; review and fix entries in a separate, user-requested cleanup pass. +Small, non-blocking friction in the repository itself — the kind that will +waste the next contributor's time too. Log it in the moment; review and fix +entries in a separate, user-requested cleanup pass. -This is not a completed-work log or a bug tracker. Never include secrets, credentials, personal data, or raw customer payloads. +This is not a completed-work log, a bug tracker, or a place for the agent's own +sandbox/shell/network hiccups. Never include secrets, credentials, personal +data, or sensitive paths. ## Open -- [ ] `2026-07-11T21:38:29Z` — `codex` — While visually testing the BadSEO design lab, a stale local process still held the configured port 8787, so Vite silently moved the app to 8788. Make the active preview URL more visible in the normal workflow or provide a reliable task-local server cleanup step. -- [ ] `2026-07-10T21:32:49Z` — `codex` — While starting the BadSEO TanStack/Cloudflare dev server in a sandbox, the Cloudflare Vite plugin failed with `listen EPERM` while probing its inspector port, even though the app port was otherwise valid. Document the need for elevated local port binding or provide an inspector-disabled validation command. -- [ ] `2026-07-10T21:28:46Z` — `codex` — While validating the standalone BadSEO package after merging its TanStack migration, `pnpm --dir badseo run typecheck` appeared to work through the root toolchain but `pnpm --dir badseo run build` could not find Vite because `badseo/node_modules` was absent. Document or enforce the required package-local install before validation. -- [ ] `2026-07-10T22:32:40Z` — `codex` — While running the badseo audit from the workspace, sandboxed TSX failed with `listen EPERM` when creating its IPC socket under the temporary directory. Rerunning the same audit with local IPC permission succeeded; provide a sandbox-compatible TSX invocation for validation scripts. -- [ ] `2026-07-10T22:23:50Z` — `codex` — While pushing the consent-banner refinement to PR #380, the SSH push hung without output and a separate remote verification hung as well; retrying the same push succeeded immediately. Surface an actionable SSH timeout or connection error instead of waiting indefinitely. -- [ ] `2026-07-10T21:36:27Z` — `codex` — While using the repository's `webapp-testing` skill, its required Python Playwright import was unavailable in both system and bundled Python. The bundled Node Playwright runtime completed the check; document or provide that fallback, including Cloudflare Vite's default port 8787 rather than Vite's usual 5173. -- [ ] `2026-07-10T21:32:10Z` — `codex` — While formatting the standalone `badseo` workspace, `pnpm exec prettier` failed because Prettier is only available from the repository root. Document the root-only formatter command or expose a workspace-local formatting script. -- [ ] `2026-07-11T15:13:43Z` — `codex` — While inspecting a BadSEO merge with login-shell commands, zsh printed `(eval):5: parse error near \`end'` before otherwise successful Git output. Running the same commands with login-shell initialization disabled avoided the noise; identify and fix the malformed shell startup hook. -- [ ] `2026-07-11T15:15:13Z` — `codex` — While resolving a merge from the sandboxed BadSEO subdirectory, `git add` could not create the parent worktree's `index.lock` despite the merge itself being allowed. Staging required the approved elevated Git path; align the workspace write boundary with the actual Git worktree root. -- [ ] `2026-07-10T21:09:27Z` — `codex` — While building the TanStack/Cloudflare badseo app, Wrangler reported an EPERM writing its debug log under the user preferences directory even though the build succeeded. Set `WRANGLER_LOG_PATH` to a writable temporary path in sandboxed build commands or make the logging failure non-fatal and quiet. -- [ ] `2026-07-10T17:53:20Z` — `codex` — While validating `.greptile/`, both `pnpm exec prettier --check` and the existing `pnpm format:check` attempted to reconcile `node_modules` and aborted because no TTY was available. Calling `node_modules/.bin/prettier` performed the non-installing check successfully; the agent/CI path needs a stable way to run package scripts without an interactive modules purge. -- [ ] `2026-07-10T18:12:35Z` — `codex` — While validating referenced files in zsh, using `path` as a loop variable overwrote zsh's special `path` array and made commands such as `git`, `jq`, and `sed` appear missing later in the same shell. Use a neutral name such as `file_path` in shell loops. +- [ ] `2026-07-14T01:28:30Z` — `claude` — Regenerating the lockfile (adding or moving a dep) makes `pnpm install` re-run the `minimumReleaseAge` gate on transitive peers already pinned at that exact version (`mysql2`, `sql-escaper`, `@aws-sdk/credential-providers`), failing the install even though nothing about them changed. `pnpm install --config.minimumReleaseAge=0` — then confirm the lockfile diff stays version-neutral — unblocks it; worth documenting that regen step so the gate doesn't re-block already-pinned versions. +- [ ] `2026-07-10T21:28:46Z` — `codex` — `pnpm --dir badseo run typecheck` works through the root toolchain but `pnpm --dir badseo run build` can't find Vite because `badseo/node_modules` is absent. Document or enforce the package-local install before validating the `badseo/` subpackage. +- [ ] `2026-07-10T21:32:10Z` — `codex` — Formatting the `badseo/` workspace with `pnpm exec prettier` fails because Prettier is only available from the repository root. Document the root-only formatter command or expose a workspace-local formatting script. ## Resolved diff --git a/.agents/skills/papercuts/SKILL.md b/.agents/skills/papercuts/SKILL.md index d89ef2a..ed3b464 100644 --- a/.agents/skills/papercuts/SKILL.md +++ b/.agents/skills/papercuts/SKILL.md @@ -1,22 +1,47 @@ --- name: papercuts -description: Log small, non-blocking repository and agent-workflow friction to .agents/PAPERCUTS.md, or review, deduplicate, and resolve existing entries. Use proactively when a tool call has to be retried, setup or documentation is confusing, a command is flaky, a cache is stale, an error is misleading, or a non-obvious gotcha wastes time. Also use when the user asks to review, fix, or clean up 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. --- # Papercuts -Capture small friction in the moment without derailing the current task. Aggregated entries show where the repository needs sanding down. +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. -## Decide whether it is a papercut +## The two-question test -A papercut is small, non-blocking friction in the repository, tooling, documentation, or agent workflow that is easy to push through but likely to waste time again. +Log it only if **both** are true: -Do not log: +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. -- A product or code correctness bug that should be fixed now or tracked as real work. -- What the agent accomplished; that belongs in the task summary. +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. -- A one-off typo with no plausible recurrence. + +When something fails, first ask "is this the repo, or is this me/my environment?" +Only the former is a papercut. ## Log proactively @@ -24,24 +49,31 @@ Do not log: 2. Append one unchecked item under `## Open` using this format: ```markdown - - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — While , . . + - [ ] `YYYY-MM-DDTHH:MM:SSZ` — `agent` — . ``` -3. Keep it to one or two sentences: what you were doing, what got in the way, and optionally the likely fix. -4. Continue the original task. Do not opportunistically expand a papercut into unrelated work. +3. 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. +4. Continue the original task. Do not expand a papercut into unrelated work. -Use UTC timestamps. Use a short agent label such as `codex`, `claude`, or `human` and include a PR or task identifier only when it helps future triage. +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 perform a broad papercut review when the user explicitly asks. Proactive behavior is limited to logging friction as it occurs. +Only mine a whole session or do a broad review when the user explicitly asks. When asked to review the file: -1. Deduplicate and group related entries. -2. Verify each open papercut still exists. -3. Fix the smallest safe, high-leverage entries first. -4. Move fixed items to `## Resolved`, check them, and append the resolving date or commit. -5. Route real bugs to normal issue/fix work. Route recurring review-policy gaps through `maintain-greptile-rules` instead of turning them into papercuts. +1. Re-run the two-question test on every open entry; delete any that fail it + (environment/shell/flake noise that slipped in). +2. Deduplicate and group related entries. +3. Verify each surviving papercut still reproduces. +4. Fix the smallest safe, high-leverage entries first. +5. 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 through `maintain-greptile-rules`. -Preserve useful history; do not delete resolved entries merely to make the file shorter. +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.) diff --git a/.claude/skills/papercuts/SKILL.md b/.claude/skills/papercuts/SKILL.md new file mode 100644 index 0000000..ed3b464 --- /dev/null +++ b/.claude/skills/papercuts/SKILL.md @@ -0,0 +1,79 @@ +--- +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. +--- + +# 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` — . + ``` + +3. 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. +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. + +When asked to review the file: + +1. Re-run the two-question test on every open entry; delete any that fail it + (environment/shell/flake noise that slipped in). +2. Deduplicate and group related entries. +3. Verify each surviving papercut still reproduces. +4. Fix the smallest safe, high-leverage entries first. +5. 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 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.)