From 84cbf3f7d809b84ccaa7ad4770f3346ffc859a2a Mon Sep 17 00:00:00 2001 From: Edwin van den Houdt Date: Fri, 4 Sep 2026 17:28:37 +0200 Subject: [PATCH] docs: use `git grep` for acceptance checks, and fix RD-09's ledger row Four acceptance commands in this backlog could not pass as written. The fourth, in RD-09, reached this backlog's own ticket files and 22 gitignored worktrees, so satisfying it literally would have rewritten the history of completed tickets. The general fix is `git grep` instead of `grep -r`: it searches tracked files only, so untracked and gitignored paths cannot pollute the result. Measured here, `grep -r` finds 132 hits under .claude/ where `git grep` finds none. RD-17, RD-18 and RD-19 are repo-wide sweeps and depend on this. Also correct RD-09's Order row. It claimed the ticket covered a generator and a skill file; neither teaches the deleted idiom, as recorded in PLAN.md. Co-Authored-By: Claude Opus 5 --- docs/project/readable-codebase/README.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/docs/project/readable-codebase/README.md b/docs/project/readable-codebase/README.md index ce5be1a..b377bbb 100644 --- a/docs/project/readable-codebase/README.md +++ b/docs/project/readable-codebase/README.md @@ -103,7 +103,7 @@ two. Note that RD-15 exists because 22 abandoned agent worktrees are still on di | RD-06 | **Bug fix:** 2 single-step forms to the effect map + retry affordance | 05 | yes | done | | RD-07 | Add `Primary` to the 3 wizard machines + specs | 05 | | done | | RD-08 | Migrate the 3 wizards to the effect map + `Primary` | 07 | yes | done | -| RD-09 | **Docs + generator:** `form-machine.hbs`, ARCHITECTURE, fp-tea, skill | 08 | | done | +| RD-09 | Teach the effect map: ARCHITECTURE §2d + fp-tea (2 docs, no generator) | 08 | | done | | RD-10 | `WizardStatus` to a payload-carrying `WizardPhase` | 08 | yes | todo | | RD-11 | Fold the lifecycle projection into `remote-data.ts`; PascalCase 3 machines | 01 | | todo | | RD-12 | `ActionState` becomes `action` on `BriefState.Loaded` | 11 | | todo | @@ -180,7 +180,7 @@ Three rules when you write a ticket file, because the agent reads its ticket and estimate and nothing can check it. `npm run lint` has an exit code. 4. **Run every acceptance command against the tree before you hand the ticket over.** A command that cannot pass is worse than no command: the agent either wastes a cycle or, - worse, "fixes" correct code to satisfy it. Three real misses so far, all in tickets written + worse, "fixes" correct code to satisfy it. Four real misses so far, all in tickets written by the supervisor: - RD-06 grepped only `runIfSubmitting`, missing that one wizard spells it `runIfIndienen`. - RD-08 grepped bare `onPrimary\|onRetry`, which can never return nothing — an unrelated @@ -188,6 +188,18 @@ Three rules when you write a ticket file, because the agent reads its ticket and - RD-08 said "no machine changes" while also requiring a repo-wide grep to come back clean, which forced comment edits in three machines. The two instructions contradicted each other. + - RD-09 grepped `docs/ apps/ libs/ .claude/`, which also matched this backlog's own ticket + files (they name the deleted method as the history of `done` work) and 22 gitignored + abandoned worktrees. Satisfying it literally would have corrupted completed-ticket + history. - Anchor greps on a declaration (`^ onRetry\(\)`) rather than a name, and make the Files - list agree with the Acceptance commands. + Three habits that prevent all four: + + - **Use `git grep`, not `grep -r`.** It searches tracked files only, so untracked and + gitignored paths never pollute the result. Measured on this repo: `grep -r` finds 132 + hits under `.claude/`, `git grep` finds 0. This matters most for RD-17, RD-18 and RD-19, + which are repo-wide sweeps. + - **Anchor on a declaration** (`^ onRetry\(\)`), not on a name that may legitimately + appear elsewhere. + - **Keep the Files list consistent with the Acceptance commands.** If a command reaches a + file the ticket says not to touch, one of the two is wrong.