Answer prose round 1: 0 🔴, 6 🟡 (0 misread); keep a project's principles folder in one place of the outside-reviewer rule, and plainer wording in the shared-environment test rules

This commit is contained in:
2026-11-18 20:32:27 +01:00
parent f9869d2fa6
commit 1f135210a6
2 changed files with 7 additions and 7 deletions
+4 -4
View File
@@ -20,10 +20,10 @@ How work proceeds in any repo, unless the repo's `AGENTS.md` says otherwise. The
- **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding. - **Implement the simplest change that solves the item, and ship it with `/larv-review`.** Whenever a test can check the change, write that test first and see it fail. Take its expected values from the item, never from the code. larv-review's reviewers hold the change to the technical principles, and a finding against one names it. Read a file in the principles folder the project's config sets (`~/.claude/bin/project-config principles` prints it) only when the item changes it, a finding or a record you write names it, or you decline a finding.
- **Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first.** An outside reviewer is a forge's auto-reviewer or a human, not one of larv-review's reviewer agents. For each finding of theirs, whether you fix it or decline it, ask why our review didn't raise it first, and change the setup so it would; a fix that only answers the comment leaves the same gap open for the next chunk. Put the change in the first place that fits: - **Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first.** An outside reviewer is a forge's auto-reviewer or a human, not one of larv-review's reviewer agents. For each finding of theirs, whether you fix it or decline it, ask why our review didn't raise it first, and change the setup so it would; a fix that only answers the comment leaves the same gap open for the next chunk. Put the change in the first place that fits:
1. A deterministic tool that would have caught it, such as a rule-hook rule, a gate check, a linter setting or `mutate-changes`: a tool catches the fault every time, and a reviewer only when it notices. 1. A deterministic tool that would have caught it, such as a rule-hook rule, a gate check, a linter setting or `mutate-changes`: a tool catches the fault every time, and a reviewer only when it notices.
2. The technical principles or review standards, where a rule was missing or too vague. 2. A technical principle or a review standard, where a rule was missing or too vague: in claude-config's files, or in the project's own principles folder.
3. Anything else: the reviewers' agents, `larv-review`'s text, or the project's own settings, principles folder or `AGENTS.md`. A client repo's `AGENTS.md` changes by a proposal of its own, per "A client project's `CLAUDE.md` and `AGENTS.md`" above. 3. Anything else: the reviewers' agents, `larv-review`'s text, or the project's own settings or `AGENTS.md`. A client repo's `AGENTS.md` changes by a proposal of its own, per "A client project's `CLAUDE.md` and `AGENTS.md`" above.
Change claude-config's files where every project gains, and the project's own only where the gap is that project's alone. In claude-config, the change is a fix of the chunk. In another project, a change to the project's own files is a fix of the chunk too, and a change to claude-config's is an item in claude-config's plan: start a worktree of claude-config off `origin/main`, run `todo-item add` in it, commit the plan file, and ship it as a pull request of its own with `chunk-pr`, since claude-config's default branch may not take a direct push. Describe the gap without the client's name, code or comment text. File a change too big for the chunk as its own item. Where no place holds the gap, as where the finding is wrong, say so in the chunk's summary rather than inventing a change. Change claude-config's files where every project gains, and the project's own only where the gap is that project's alone. In claude-config, the change is a fix of the chunk. In another project, a change to the project's own files is a fix of the chunk too, and a change to claude-config's is an item in claude-config's plan: start a worktree of claude-config off `origin/main`, run `todo-item add` in it, commit the plan file, and ship it as a pull request of its own with `chunk-pr`, since claude-config's default branch may not take a direct push. Describe the gap without the client's name, code or comment text. File a change too big for the chunk as its own item. Where no setup gap caused the finding, as when the finding is wrong, say so in the chunk's summary rather than inventing a change.
- **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: `finish` there refuses `--changelog`. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5). - **Remove a finished item from the plan, and revise any decision that cites it.** If the repo publishes something others consume — a package, an image, an API — reword the item for them and move it to `CHANGELOG.md` under `## Unreleased`. A changelog is for the public, never for the next agent. Otherwise delete it; git history is the record. `~/.claude/bin/todo-item finish <ID>` removes the item with its detail, and adds the bullet you pass with `--changelog <bullet>`; it refuses while a decision cites the item. A plan kept in Jira takes no bullet, since the issues' history is its changelog: `finish` there refuses `--changelog`. A chunk finishes its items as it merges, through `chunk-pr merge --finish <ID>`, which takes the same flags (`larv-review` §5).
- **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision. - **Releases are the human's.** The version bump and the publishing credentials are theirs, whatever another rule says. Prepare everything else, so cutting a release is one decision.
- **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`. - **Open each plan item or ticket with a bold one-sentence tagline**, so the taglines alone say what a release holds. The tagline states the target state, checkable when done: an imperative verb plus what holds afterwards. A present-tense fact reads as the current state and doesn't say anything about what to do. Add "today X" only where the direction is otherwise ambiguous. GOOD: `**Accept undefined in MetadataValue and drop such keys on output.**` BANNED: `MetadataValue accepts undefined; such keys are dropped on output`.
@@ -106,7 +106,7 @@ The rules only reviewers apply, for quality, comments, READMEs and prose, are th
- Branch for a plan item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them. Under a `branch` template, `chunk-preflight` names both by the template. - Branch for a plan item without a ticket: `item-<ID>`, in the worktree `<checkout>-item-<ID>` beside the checkout, as `chunk-preflight` makes them. Under a `branch` template, `chunk-preflight` names both by the template.
- Where the project's config keeps a file in the config's folder, `~/.claude-projects/<key>/`, such as the plan or a record, commit each change you make to that file in the folder's own git repo, on its only branch. Two chunks may commit there at once, so commit only that file: `git commit -m <title> -- <file>`, after `git add <file>` where it is new. Where git finds `index.lock` held, the other chunk is committing: try again. Title that commit as you would title the change in the checkout: where a commit in the checkout goes with it, give it the same title. - Where the project's config keeps a file in the config's folder, `~/.claude-projects/<key>/`, such as the plan or a record, commit each change you make to that file in the folder's own git repo, on its only branch. Two chunks may commit there at once, so commit only that file: `git commit -m <title> -- <file>`, after `git add <file>` where it is new. Where git finds `index.lock` held, the other chunk is committing: try again. Title that commit as you would title the change in the checkout: where a commit in the checkout goes with it, give it the same title.
- Use `gh` on GitHub remotes and `tea` on Gitea remotes (e.g. `gitea.larvit.se`) — same command shape: `tea pr list|create`, `tea issue`, `tea release`, `tea api`. Everything in this section applies to both. - Use `gh` on GitHub remotes and `tea` on Gitea remotes (e.g. `gitea.larvit.se`) — same command shape: `tea pr list|create`, `tea issue`, `tea release`, `tea api`. Everything in this section applies to both.
- On GitHub and Gitea, open a chunk's pull request as a draft, when `larv-review` §2 says, mark it ready and merge it with `~/.claude/bin/chunk-pr`, which picks `gh` or `tea` from the remote; `chunk-pr --help` says how. Once it has merged, run `chunk-pr clean` in the chunk's worktree: it removes the worktree and the branch and fast-forwards the main checkout. - On GitHub and Gitea, open a chunk's pull request as a draft, mark it ready and merge it with `~/.claude/bin/chunk-pr`, which picks `gh` or `tea` from the remote; `chunk-pr --help` says how. Once it has merged, run `chunk-pr clean` in the chunk's worktree: it removes the worktree and the branch and fast-forwards the main checkout.
## Handoffs ## Handoffs
- Write no handoff document. The repo holds everything the next session needs: the plan, the decisions, and every script, sketch or measurement those depend on. A file outside the repo is unreachable from another machine's checkout. - Write no handoff document. The repo holds everything the next session needs: the plan, the decisions, and every script, sketch or measurement those depend on. A file outside the repo is unreachable from another machine's checkout.
+3 -3
View File
@@ -10,12 +10,12 @@
- Services and networking: a deploy trigger, health probe, backup job or admin path gets its own way in, since one routed through the application it operates on fails in exactly the state it exists for. BANNED: a deploy webhook reached through the app's own reverse proxy. GOOD: its own listener, answering while the app is down. - Services and networking: a deploy trigger, health probe, backup job or admin path gets its own way in, since one routed through the application it operates on fails in exactly the state it exists for. BANNED: a deploy webhook reached through the app's own reverse proxy. GOOD: its own listener, answering while the app is down.
- Modules: dependencies point one way. Callers may know the service; the service never knows its callers, and neither it nor its comments name or assume the delivery mechanism (controller, HTTP, request validation, route), because a queue worker, a CLI or another service may call it too. BANNED: `// The controller's validator guarantees these fields`. GOOD: "callers must supply X", or the guard and the type signature alone. - Modules: dependencies point one way. Callers may know the service; the service never knows its callers, and neither it nor its comments name or assume the delivery mechanism (controller, HTTP, request validation, route), because a queue worker, a CLI or another service may call it too. BANNED: `// The controller's validator guarantees these fields`. GOOD: "callers must supply X", or the guard and the type signature alone.
- Functions: a function takes what it needs as arguments and returns what it produces. One that works only after another has set up shared state, or leaves state for the next to find, is entangled with it. BANNED: `validate(conf)` that fills defaults `send(conf)` relies on. GOOD: `send(withDefaults(conf))`. - Functions: a function takes what it needs as arguments and returns what it produces. One that works only after another has set up shared state, or leaves state for the next to find, is entangled with it. BANNED: `validate(conf)` that fills defaults `send(conf)` relies on. GOOD: `send(withDefaults(conf))`.
- Tests and tooling: a test, script or pipeline stage that passes only because another ran first is entangled; it states what it needs and gets it. A test on a shared environment, one that other tests, people or a second copy of the test use at the same time, also holds these rules: - Tests and tooling: a test, script or pipeline stage that passes only because another ran first is entangled; it states what it needs and gets it. A shared environment is one that other tests, people or a second copy of the test use at the same time. A test on one also holds these rules:
- Assert only on records the test created and can name, never on a count or the first row. BANNED: `expect(rows.length).toBe(3)`; `expect(rows[0].name).toBe("Ada")`. GOOD: `expect(rows.find((row) => row.id === created.id)).toMatchObject({ name: "Ada" })`. - Assert only on records the test created and can name, never on a count or the first row. BANNED: `expect(rows.length).toBe(3)`; `expect(rows[0].name).toBe("Ada")`. GOOD: `expect(rows.find((row) => row.id === created.id)).toMatchObject({ name: "Ada" })`.
- Never change state the test doesn't own. BANNED: a test that turns off a setting every tenant shares, or empties a table to start clean. GOOD: the test creates a tenant and changes the setting there. - Never change state the test doesn't own. BANNED: a test that turns off a setting every tenant shares, or empties a table to start clean. GOOD: the test creates a tenant and changes the setting there.
- Pass in any order, and beside a second copy of the test running at the same time. BANNED: a fixture user named `test-user@example.com`. GOOD: `user-${unique}@example.com`, where the test made `unique` for this run; such a name is an identity, not the seeded randomness the test bullet below asks for. - Pass in any order, and beside a second copy of the test running at the same time. BANNED: a fixture user named `test-user@example.com`. GOOD: `user-${unique}@example.com`, where the test made `unique` for this run.
- A helper registers its teardown before it creates anything, keyed by a value it made itself, and the teardown deletes only what it can name. BANNED: create the order, then register `DELETE FROM orders WHERE created_at > :start`. GOOD: make a reference, register `DELETE FROM orders WHERE reference = :reference`, then create the order under it. - A helper registers its teardown before it creates anything, keyed by a value it made itself, and the teardown deletes only what it can name. BANNED: create the order, then register `DELETE FROM orders WHERE created_at > :start`. GOOD: make a reference, register `DELETE FROM orders WHERE reference = :reference`, then create the order under it.
- A helper that saves checks what was saved, never the status code alone. BANNED: `expect(response.status).toBe(200)` as the helper's only check. GOOD: read the record back and compare each field the helper set. - A helper that saves a record checks what was saved, never the status code alone. BANNED: `expect(response.status).toBe(200)` as the helper's only check. GOOD: read the record back and compare each field the helper set.
- Proximity is not a reason. Reusing a listener, config file, table, module or service because it is already there, when the new thing has no relationship to it, is how entanglement gets in. If you cannot name the seam, there is none. - Proximity is not a reason. Reusing a listener, config file, table, module or service because it is already there, when the new thing has no relationship to it, is how entanglement gets in. If you cannot name the seam, there is none.
* Functional core, imperative shell — a core rule beside "Compose, do not entangle": no other principle overrides it. * Functional core, imperative shell — a core rule beside "Compose, do not entangle": no other principle overrides it.
- Decisions live in pure functions, data in and data out; the shell around them performs the effects and holds no branching of its own. - Decisions live in pure functions, data in and data out; the shell around them performs the effects and holds no branching of its own.