From f9869d2fa672606f3b7c467fc69e2c7c5834f701 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 18 Nov 2026 20:32:27 +0100 Subject: [PATCH] =?UTF-8?q?Answer=20product-owner=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=201=20=F0=9F=9F=A1=20(1=20misread);=20count=20a?= =?UTF-8?q?=20coding=20convention=20as=20a=20technical=20principle=20for?= =?UTF-8?q?=20stability=20and=20product-owner,=20name=20the=20CI=20cases?= =?UTF-8?q?=20by=20what=20starts=20a=20run,=20and=20say=20which=20reviewer?= =?UTF-8?q?s=20read=20the=20conventions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- agents/product-owner-reviewer.md | 2 +- agents/stability-reviewer.md | 4 ++-- bin/project_config/main.py | 4 ++-- bin/project_config/settings.py | 2 +- skills/larv-review/SKILL.md | 18 +++++++++--------- skills/larv-review/review-findings.md | 2 +- 7 files changed, 17 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 3718e5ce..64eb706e 100644 --- a/README.md +++ b/README.md @@ -109,7 +109,7 @@ A project may also set `env-file`, the file of `KEY=value` credentials its tools A project may also set `touch-predictions`, a path spelt as `changelog`'s is, such as `touch-predictions = "checkout:docs/touch-predictions.md"`. `touch-predictions record` appends each chunk's predicted files and parts there, beside those it touched. A project that leaves it out keeps no such record. -A project whose team wrote its own coding conventions lists the files in `coding-conventions`, each spelt as `changelog` is, such as `coding-conventions = ["checkout:CONVENTIONS.md"]`. Every reviewer reads them beside the principles and the standards, and the team's rule wins where they conflict. +A project whose team wrote its own coding conventions lists the files in `coding-conventions`, each spelt as `principles` is, such as `coding-conventions = ["checkout:CONVENTIONS.md"]`. Each reviewer agent larv-review launches reads them beside the principles and the standards, and the team's rule wins where they conflict. A project may also set `notifier` to `"mattermost"` or `"slack"`, the service that sends loop-claude's DMs. The `env-file` then holds that service's keys. A project that sets none gets no DMs, whatever its env file holds. `project-config notifier` prints the setting. diff --git a/agents/product-owner-reviewer.md b/agents/product-owner-reviewer.md index 48051dc1..17e9ca32 100644 --- a/agents/product-owner-reviewer.md +++ b/agents/product-owner-reviewer.md @@ -47,7 +47,7 @@ Before anything else, **read the technical principles** in the folder your promp ## Your Output Format -Report only a defect a persona hits; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle. Friction that is none of these is not a finding. +Report only a defect a persona hits; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); or a breach of a technical principle, or of a coding convention, which counts as one. Friction that is none of these is not a finding. Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict: diff --git a/agents/stability-reviewer.md b/agents/stability-reviewer.md index c7e436e1..6148799b 100644 --- a/agents/stability-reviewer.md +++ b/agents/stability-reviewer.md @@ -127,13 +127,13 @@ Every PR gets at least this sweep. - Were tests and implementation changed together in a way that could mask a regression — e.g. an assertion weakened to make a test pass? Flag it; these should be separate changes. - Does each test earn its keep, as the technical principles' test bullet says? Look at where its expected values come from, what it asserts, what it mocks, what wording it pins, whether another test already pins the behaviour, and whether it sleeps or reads the wall clock. - Does a test decide at run time whether to check anything, by a conditional skip, early return or catch around its assertions, as the technical principles' test bullet forbids? Flag it. -- Does a test that runs on a shared environment hold the rules for one in the technical principles' "Compose, do not entangle" → "Tests and tooling"? Does the test that covers a seam to a service the team runs mock that service, which the test bullet's "Never mock a service your own team runs" forbids? +- Does a test that runs on a shared environment hold the rules for such a test in the technical principles' "Compose, do not entangle" → "Tests and tooling"? Does the test that covers a seam to a service the team runs mock that service, which the test bullet's "Never mock a service your own team runs" forbids? - Are there untestable side effects that should be refactored? ## Output Format -Report only a defect; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out. +Report only a defect; a requirement that the change breaks, of the plan in the file your prompt's `Plan:` line names, of the goals in the file your prompt's `Goals and audience:` line names, or of code health (`~/.claude/CLAUDE.md` → "Shared goal", unless that file voids it); a breach of a technical principle, or of a coding convention, which counts as one; and the places the prompt hands you. A finding that is none of these is noise, however true: leave it out. Verdict, severities and rounds: ~/.claude/skills/larv-review/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis, mutation — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then the findings, most severe first, each with: - **Location**: File and line/function diff --git a/bin/project_config/main.py b/bin/project_config/main.py index 9a00b4c5..05b7ad15 100644 --- a/bin/project_config/main.py +++ b/bin/project_config/main.py @@ -79,8 +79,8 @@ Left out, the project keeps no such record. It is printed with the others only w `coding-conventions` is an optional setting, a list of paths spelt as the others are: the files in which the project's team wrote its own coding conventions, such as -`coding-conventions = ["checkout:CONVENTIONS.md"]`. Every reviewer reads them beside the principles -and the standards, and the team's rule wins where they conflict. `project-config coding-conventions` +`coding-conventions = ["checkout:CONVENTIONS.md"]`. Each reviewer agent larv-review launches reads +them beside the principles and the standards, and the team's rule wins where they conflict. `project-config coding-conventions` prints one path a line. Left out, the reviewers read no such file. It is printed with the others only where it is set. diff --git a/bin/project_config/settings.py b/bin/project_config/settings.py index 2032431b..f7351e9f 100644 --- a/bin/project_config/settings.py +++ b/bin/project_config/settings.py @@ -48,7 +48,7 @@ PULL_REQUEST_TITLE = "pull-request-title" BRANCH = "branch" # An optional path setting: main's help says what it places. TOUCH_PREDICTIONS = "touch-predictions" -# An optional setting: a list of paths, each spelt as SPELLING says, to the files that hold the team's own coding conventions, which every reviewer reads. Three readers, seated as the human who writes a client's config, picked the spelling 2-1 from four candidates, over a bare `conventions`, which they confused with `principles` and `working-rules`. +# An optional setting: a list of paths, each spelt as SPELLING says, to the files that hold the team's own coding conventions, which each reviewer agent larv-review launches reads. Three readers, seated as the human who writes a client's config, picked the spelling 2-1 from four candidates, over a bare `conventions`, which they confused with `principles` and `working-rules`. CODING_CONVENTIONS = "coding-conventions" # Two optional settings, each a name, set together and only where `plan` names a Jira epic: the name of the workflow transition that finishes an item, and of the status it must lead to. Three readers, seated as the human who writes a client's config, picked the spelling from four candidates: two flat keys, as the other settings are, with a prefix that says what they apply to. JIRA_FINISH_TRANSITION = "jira-finish-transition" diff --git a/skills/larv-review/SKILL.md b/skills/larv-review/SKILL.md index 71930770..806e796e 100644 --- a/skills/larv-review/SKILL.md +++ b/skills/larv-review/SKILL.md @@ -22,12 +22,12 @@ The bar a chunk is reviewed to: `quality.md` in the project's review standards, ## 2. Ship the branch (idempotent — skip whatever already exists) -Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the default branch. Commit. When the pull request opens depends on what starts the repo's CI, which its CI config says, as a workflow file's `on:` does: +Follow `~/.claude/CLAUDE.md` → "Git, commits, and PRs". Never commit to the default branch. Commit. Then read in the repo's CI config, such as a workflow file's `on:`, what starts a CI run: -- **CI runs on pushed branches** → open no pull request yet. Push with `git push --set-upstream origin ` now and after each commit, so CI cycles while the review runs. §4 opens the pull request once our own review is done: a forge's auto-reviewer reviews a draft, and human reviewers see it, so an early draft draws findings our passes would have caught. -- **CI runs only on pull requests, or the repo has no CI** → run `~/.claude/bin/chunk-pr open '' '<summary>'` now: it pushes with upstream set and opens a **draft** PR, so CI cycles while the review runs. +- **A push to the chunk's branch starts one** → open no pull request yet. Push with `git push --set-upstream origin <branch>` now and after each commit, so CI cycles while the review runs. §4 opens the pull request once our own review is done: human reviewers see a draft, and a forge's auto-reviewer may review one, so an early draft draws findings our passes would have caught. +- **Only a pull request starts one, or the repo has no CI** → run `~/.claude/bin/chunk-pr open '<title>' '<summary>'` now: it pushes with upstream set and opens a **draft** PR, so CI cycles while the review runs. -Say in the summary which order the chunk took. No remote → review locally and say so in the summary. +No remote → review locally and say so in the summary. **Work in the worktree.** Enter the chunk's worktree with the `EnterWorktree` tool, `path` set to it, unless the session already works there. A reviewer, a seat and the security pass's skill read the diff of the session's working directory, and a subagent starts there; from the checkout root they find the branch's diff empty. @@ -37,7 +37,7 @@ Say in the summary which order the chunk took. No remote → review locally and **Mutation tests.** Where the branch changes code, run the project's mutation command in the chunk's worktree, with every change committed, before each stability round: the one the project's README documents, else `~/.claude/bin/run-heavy ~/.claude/bin/mutate-changes --prefix '<how the project runs its tools>'`. `mutate-changes --help` says how to set `--prefix` and `--jobs`. Where a mutant of a changed line survives and changes behaviour, kill it: add or strengthen a test that fails on it, commit, and run the command again. Hand stability-reviewer what the last run printed, with the commit it ran on. On exit 1, repair what its message names and run it again; when you cannot, hand the reviewer the message. -Where `mutate-changes` prints `Not mutated, as no tool covers their language:` and names code among those files, file a plan item titled `**Add a mutation tool for <language>.**`, scored per `~/.claude/rules/todo-items.md`. Its detail names the language's mutation tool, pinned to a version that supports the project's language version, and the files the line named. Where an earlier chunk filed the item, add this chunk's files to its detail instead. A file that holds no code, such as Markdown or a config file, files no item. +Where `mutate-changes` prints `Not mutated, as no tool covers their language:` and that line names a file of code, not only Markdown or config files, file a plan item titled `**Add a mutation tool for <language>.**`, scored per `~/.claude/rules/todo-items.md`. Its detail names the language's mutation tool, pinned to a version that supports the project's language version, and the code files the line named. Where an earlier chunk filed the item, add this chunk's files to its detail instead. ## 3. Passes @@ -149,7 +149,7 @@ Launch systems-architect: review the whole project as the release leaves it; the ### Principles -Launch one principles-auditor on the trigger in §3, so the project is read once per round. Hand it the goals file's goals, from the header's `Goals and audience:` line, and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, and each file in the config's principles folder (`~/.claude/bin/project-config principles` prints it) whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff, and each file the header's `Coding conventions:` line names. A file without the line applies to every project. Unsure → hand it the file. +Launch one principles-auditor on the trigger in §3, so the project is read once per round. Hand it the goals file's goals, from the header's `Goals and audience:` line, and code health (`~/.claude/CLAUDE.md` → "Shared goal") unless that file voids it, and each file in the config's principles folder (`~/.claude/bin/project-config principles` prints it) whose `Applies to` line the project meets, judged from the README, `git ls-files` and the branch diff. A file without the line applies to every project. Unsure → hand it the file. Hand it each file the header's `Coding conventions:` line names too. ### Comprehension check @@ -190,7 +190,7 @@ Launch override-reviewer with each line `rule-hook overrides` prints that no ear ### Stability and product-owner -Launch the reviewer with the change — stability-reviewer also with the places per "Comprehension check" → "Places", the commit §2's tests and static analysis last passed on, and what the mutation command printed, with its commit, per §2 → "Mutation tests", product-owner-reviewer with the external surface it touches. Each reports only a defect, a requirement of the plan or the goals the change breaks, a breach of a technical principle, or, for stability-reviewer, a place per "Comprehension check" → "Places"; drop any other finding. Fix along the reviewer's Fix guidance (delete > simplify > modify > add). The defect a persona hits is as often in wording or an upgrade path as in code, so a product-owner fix is as often a message or a doc. +Launch the reviewer with the change — stability-reviewer also with the places per "Comprehension check" → "Places", the commit §2's tests and static analysis last passed on, and what the mutation command printed, with its commit, per §2 → "Mutation tests", product-owner-reviewer with the external surface it touches. Each reports only a defect, a requirement of the plan or the goals the change breaks, a breach of a technical principle or of a coding convention, or, for stability-reviewer, a place per "Comprehension check" → "Places"; drop any other finding. Fix along the reviewer's Fix guidance (delete > simplify > modify > add). The defect a persona hits is as often in wording or an upgrade path as in code, so a product-owner fix is as often a message or a doc. ### Prose @@ -203,7 +203,7 @@ Launch prose-reviewer with what the diff touched and every section this review c 3. The forge's checks: `chunk-pr merge` waits for them to pass (§5 step 4). A red check is a finding. 4. No CI configured → the gate is local tests only; note it in the summary. 5. The local tests green → where §2 left the pull request unopened, open it with `~/.claude/bin/chunk-pr open '<final title>' '<summary>'` and mark it ready at once with `~/.claude/bin/chunk-pr ready`. Otherwise mark the PR ready with `~/.claude/bin/chunk-pr ready '<final title>'`, which sets the title as it marks the PR ready. -6. **External auto-reviewer**, when the repo has one — its config file (`.coderabbit.yaml` and the like), or its comments on earlier PRs; none → skip it, say so. Marking the PR ready is what summons it. Wait up to **10 minutes** for its first review, checking about once a minute; nothing by then → note it in the summary and carry on, never waiting twice. Its rounds, §3 → "Round cap". Once it has reviewed, each later return here before its cap, after a fix re-entered per §3, waits up to **5 minutes** for its re-review of the new commit. Each of its findings, fixed or declined, ends with the setup change that `~/.claude/CLAUDE.md` → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first" asks for. +6. **External auto-reviewer**, when the repo has one — its config file (`.coderabbit.yaml` and the like), or its comments on earlier PRs; none → skip it, say so. Marking the PR ready summons it, unless it reviewed the draft already. Wait up to **10 minutes** for its first review, checking about once a minute; nothing by then → note it in the summary and carry on, never waiting twice. Its rounds, §3 → "Round cap". Once it has reviewed, each later return here before its cap, after a fix re-entered per §3, waits up to **5 minutes** for its re-review of the new commit. Each of its findings, fixed or declined, ends with the setup change that `~/.claude/CLAUDE.md` → "Working loop", "Change the setup for each finding an outside reviewer raises on a PR, deterministic tools first" asks for. ## 5. Goal alignment, then merge @@ -214,7 +214,7 @@ Launch prose-reviewer with what the diff touched and every section this review c - **A merge conflict.** Resolve it, commit and push. Rerun only the passes whose triggers the resolution's own lines meet (§3), each in a round of its own. - **A paired ruling to run again.** `chunk-pr merge` has merged the default branch in and pushed. Run the ruling at that head, record it, commit and push. Don't return to §4 for it: the next turn waits for the checks at the new head. - **An owed scoring run, or a queue another pull request holds.** Record the run, or wait, as the message says. - - **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. It ends with the same setup change (§4 step 6), fixed or declined. The wait doesn't hold the queue, so other chunks merge meanwhile. + - **A reviewer's comment**, where the project's config sets `wait-for-approval` (`chunk-pr --help`) and the pull request waits for a human's approval. Answer it in its thread on the forge, and fix what it asks as a finding of the chunk. Fixed or declined, it ends with the same setup change (§4 step 6). The wait doesn't hold the queue, so other chunks merge meanwhile. A repo whose `AGENTS.md` names another method merges that way with the forge's CLI instead, after it finishes the chunk's items with `todo-item finish` in the branch, and once the pull request's checks pass, `~/.claude/bin/larv-review scoring-run-owed` exits 0 and, where `~/.claude/bin/project-config wait-for-approval` prints `true`, GitHub reports the pull request approved. A repo withholds this in its `AGENTS.md` → leave the PR ready and unmerged, and say which line withheld it. 5. Merged → run `~/.claude/bin/chunk-pr clean` in the chunk's worktree, and put a failure it prints in the summary. diff --git a/skills/larv-review/review-findings.md b/skills/larv-review/review-findings.md index 2ca50950..ca617dbd 100644 --- a/skills/larv-review/review-findings.md +++ b/skills/larv-review/review-findings.md @@ -14,7 +14,7 @@ A reviewer reads and reports; it doesn't edit anything. It writes no file but it A finding against a technical principle names it and the file in the config's principles folder it lives in. A finding against `quality.md`, in the folder your prompt's `Review standards:` line names, names that file and the rule it breaks. -Where your prompt has a `Coding conventions:` line, read each file it names beside the principles and the standards: they are the rules of the project's team. Where one conflicts with a principle or a standard, the team's rule wins, and a finding against a convention names its file. +Where your prompt has a `Coding conventions:` line, read each file it names beside the principles and the standards: they are the rules of the project's team, and a breach of one counts as a breach of a technical principle. Where one conflicts with a principle or a standard, the team's rule wins, and a finding against a convention names its file. ## Misread