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.