From 0d5e3e7fe9fb85fd6106985381f77590de48033a Mon Sep 17 00:00:00 2001 From: Hatton Date: Fri, 10 Jul 2026 16:58:12 -0600 Subject: [PATCH 1/2] Add papercut log: capture small improvement ideas without derailing work PAPERCUTS.md is a lightweight, committed log where agents and devs jot down dev/agent/tooling friction (stale docs, script quirks, workflow snags) in the moment, to be triaged and trimmed later. AGENTS.md gains a rule telling agents to log such cuts proactively. The full procedure is the new `papercut` skill in the bloom-team-skills repo. Seeded with a first real cut hit while committing this change: the pre-commit hook fails confusingly when node_modules is empty. Co-Authored-By: Claude Fable 5 --- AGENTS.md | 8 ++++++++ PAPERCUTS.md | 31 +++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 PAPERCUTS.md diff --git a/AGENTS.md b/AGENTS.md index 4224fc54ffaf..453729b66a97 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,14 @@ All public methods should have a comment. So should most private ones! # Git Committing Always include a good description when creating a git commit. +# Papercuts +When you hit tooling/process friction, have to work around something, or learn something these +docs should have told you — and now isn't the time to fix it — append a short entry to +`PAPERCUTS.md` at the repo root (format in that file's header). Don't make a separate commit +for it (it rides along in your next commit), don't derail your current task, and mention the +logged cut in your final report. Cuts about the environment or team workflow (not this repo) +go in your local bloom-team-skills clone's `PAPERCUTS.md` instead, if you have one. + # Skills Reusable, task-specific procedures for this repo live in `.github/skills//SKILL.md`. When a request matches one of these, READ the matching `SKILL.md` and follow it as the diff --git a/PAPERCUTS.md b/PAPERCUTS.md new file mode 100644 index 000000000000..46744f6551c5 --- /dev/null +++ b/PAPERCUTS.md @@ -0,0 +1,31 @@ +# Papercuts + +Small dev/agent/tooling friction points and improvement ideas — captured in the moment, +fixed later. This file holds cuts about **this repo** (its docs, scripts, build, tests, +agent experience); cuts about the environment, machine, or team workflow go in +bloom-team-skills' `PAPERCUTS.md`. The full procedure is the `papercut` skill in +https://github.com/BloomBooks/bloom-team-skills. + +House rules: + +- Add new entries at the **top**, directly under this header block. +- Entry format: `## YYYY-MM-DD — Title`, then `- **Cut:**` / `- **Idea:**` / optional + `- **Context:**` lines. 2–5 lines total. +- Hit the same cut again? Add a dated `seen again: ...` line to the existing entry instead of + duplicating it. +- On a merge conflict here, keep both sides' entries. +- Product bugs/features go to YouTrack instead. +- To work through the backlog, run the `papercut` skill in trim mode ("trim the papercuts"). + Fixed, promoted, or stale entries get **deleted** — the log only contains open cuts. + +--- + +## 2026-07-10 — Pre-commit hook fails confusingly when node_modules is empty + +- **Cut:** With `src/BloomBrowserUI/node_modules` empty (e.g. a fresh checkout/worktree after + the pnpm migration, before `pnpm install`), `git commit` fails with + `pretty-quick: command not found` — and since the hook runs mid-command, the failed commit + is easy to miss. +- **Idea:** Have `.vite-hooks/pre-commit` check for `node_modules/.bin/pretty-quick` first and + fail with "front-end dependencies not installed — run `pnpm install` in src/BloomBrowserUI". +- **Context:** Hit while committing this very file. From b7ccd1cf779bd3ab75a58402d725cd0df9e8524d Mon Sep 17 00:00:00 2001 From: John Hatton Date: Mon, 13 Jul 2026 17:09:08 -0600 Subject: [PATCH 2/2] Apply suggestion from @greptile-apps[bot] Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 453729b66a97..7deb7d1905c6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -64,7 +64,7 @@ Always include a good description when creating a git commit. # Papercuts When you hit tooling/process friction, have to work around something, or learn something these -docs should have told you — and now isn't the time to fix it — append a short entry to +docs should have told you — and now isn't the time to fix it — prepend a short entry to `PAPERCUTS.md` at the repo root (format in that file's header). Don't make a separate commit for it (it rides along in your next commit), don't derail your current task, and mention the logged cut in your final report. Cuts about the environment or team workflow (not this repo)