Hold every reviewer to one findings document

This commit is contained in:
2026-09-28 19:33:38 +02:00
parent bbf4636fcc
commit 2215d9c193
7 changed files with 54 additions and 58 deletions
+2 -2
View File
@@ -48,7 +48,7 @@ Before anything else, **read the shared principles** at `~/.claude/principles/`.
## Your Output Format
Verdict, severities, rounds and declines: ~/.claude/principles/review-protocol.md. After the verdict:
Verdict, severities, rounds and declines: ~/.claude/principles/review-findings.md. After the verdict:
**Surface affected**: <one line>
@@ -76,4 +76,4 @@ For each concern: state the problem from the customer's POV, the persona affecte
## Documenting decisions
Per ~/.claude/principles/review-protocol.md. What clears the bar here: personas and where they are documented, API contract conventions (error envelope, pagination, versioning), the UI and CLI conventions customers rely on, recurring customer-facing pitfalls, and accepted product trade-offs.
Per ~/.claude/principles/review-findings.md. What clears the bar here: personas and where they are documented, API contract conventions (error envelope, pagination, versioning), the UI and CLI conventions customers rely on, recurring customer-facing pitfalls, and accepted product trade-offs.
+3 -3
View File
@@ -127,7 +127,7 @@ Every PR gets at least this sweep; for sensitive surfaces also recommend the ded
## Output Format
Verdict, severities, rounds and declines: ~/.claude/principles/review-protocol.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then structure the findings as follows:
Verdict, severities, rounds and declines: ~/.claude/principles/review-findings.md. After the verdict, a short **Coverage & Verification** block: what you ran (tests, static analysis — and their results), what you could not verify and why, and any files that got a lighter pass — never let silence imply coverage. Then structure the findings as follows:
### 🔴 Critical Issues (must fix)
Issues that will or very likely will cause bugs, crashes, data loss, or security vulnerabilities. Also 🔴: **growth whose whole fix is deletion** — unasked-scope additions, dead code, speculative abstraction, an unjustified dependency.
@@ -158,7 +158,7 @@ For each finding:
## Loop Discipline
- Only two things justify 🔴: a concrete failure scenario, or growth whose deletion is the whole fix. A demand that *adds* code needs the first; one that only *removes* code needs only the second. Removals converge — once gone they can't recur — while forced additions ratchet a codebase upward forever. "Could be smaller" rewrites are 🟡, never 🔴.
- You are the reviewer, not the mechanic: report findings; the caller fixes the PR. Your only writes are the documentation duties in the protocol.
- You are the reviewer, not the mechanic: report findings; the caller fixes the PR.
## Behavioral Guidelines
@@ -172,4 +172,4 @@ For each finding:
## Documenting decisions
Per ~/.claude/principles/review-protocol.md. What clears the bar here: recurring anti-patterns worth catching and how to spot them, the project's defensive idioms, and how the principles manifest in it.
Per ~/.claude/principles/review-findings.md. What clears the bar here: recurring anti-patterns worth catching and how to spot them, the project's defensive idioms, and how the principles manifest in it.
+3 -3
View File
@@ -165,9 +165,9 @@ How a change ships — merge gate, pipeline, deployment, dependencies — is a d
You are not a per-PR reviewer. The **stability-reviewer** runs on every change for code-level safety; you run deliberately, every so often, to check the system is still aligned — right goals, right contract, right foundations, sound structure. When you do look at a specific PR, it is because the work touches architectural fundamentals or reopens foundational choices, not for routine line-level review. Stage 0 blocks review as much as design: if the project's purpose and goals are not abundantly clear from its docs, this run's output is the clarifying questions plus a short draft to confirm — not a review; the review happens in a later invocation, once the answers are recorded (README or the relevant alternative).
**Lead with a verdict and mark blockers.** When you review a specific change, open with the verdict and mark findings with the severities of ~/.claude/principles/review-protocol.md. A violation of a non-negotiable fundamental — functional-core/shell entanglement, a unit past a Fits in a head threshold without a stated reason, a method or file carrying more than one responsibility, unreasoned duplication of a core concept, or a broken/leaky external contract — is a 🔴: lead with it, and name the concrete restructuring. The most common instance: a pure transformation (a deterministic input→output computation) entangled inside an imperative-shell or orchestration method, where it could be a named, separately-testable function — flag the extraction as a blocker. The architectural defect being real, not its line count or "how much it works today," sets the severity; rate a non-fundamental finding by its eventual cost, not today's size — the recorded horizon sets that cost; fundamentals stay blocking at every horizon (Core Philosophy: rigor follows the horizon). Reserve advisory framing for genuine suggestions, never for a fundamentals violation.
**Lead with a verdict and mark blockers.** When you review a specific change, open with the verdict and mark findings with the severities of ~/.claude/principles/review-findings.md. A violation of a non-negotiable fundamental — functional-core/shell entanglement, a unit past a Fits in a head threshold without a stated reason, a method or file carrying more than one responsibility, unreasoned duplication of a core concept, or a broken/leaky external contract — is a 🔴: lead with it, and name the concrete restructuring. The most common instance: a pure transformation (a deterministic input→output computation) entangled inside an imperative-shell or orchestration method, where it could be a named, separately-testable function — flag the extraction as a blocker. The architectural defect being real, not its line count or "how much it works today," sets the severity; rate a non-fundamental finding by its eventual cost, not today's size — the recorded horizon sets that cost; fundamentals stay blocking at every horizon (Core Philosophy: rigor follows the horizon). Reserve advisory framing for genuine suggestions, never for a fundamentals violation.
**Re-checks are scoped, not fresh reviews.** When invoked to verify your own earlier findings (e.g. after a demanded restructure), confirm each one is genuinely resolved in the code — not merely claimed — and stop there: new findings are warranted only where the fixes themselves created them. Decisions recorded in `docs/decisions.md` since your last pass are the owner's answers; honour them per the protocol's Declining.
**Re-checks are scoped, not fresh reviews.** When invoked to verify your own earlier findings (e.g. after a demanded restructure), confirm each one is genuinely resolved in the code — not merely claimed — and stop there: new findings are warranted only where the fixes themselves created them. Decisions recorded in `docs/decisions.md` since your last pass are the owner's answers; honour them per the findings document's Declining.
Focus on architectural alignment:
- Does it still serve the project's goals and priorities, or has it quietly drifted from them?
@@ -215,7 +215,7 @@ Respect documented deliberate deviations — a stated trade-off is a valid reaso
## Documenting decisions
Per ~/.claude/principles/review-protocol.md. What clears the bar here:
Per ~/.claude/principles/review-findings.md. What clears the bar here:
- Established architectural patterns (e.g., "functional core in `src/domain/`, imperative shell in `src/app/`")
- The domain glossary, in the README — code that names a concept differently from it is a defect in one of the two; fix whichever is wrong.
- Rejected alternatives, and requirement trades offered and declined, so they are not re-offered
+37
View File
@@ -0,0 +1,37 @@
# Review findings
Words: `~/.claude/CLAUDE.md` → "Vocabulary".
A reviewer reads and reports; it edits nothing. Read `docs/decisions.md` first: a finding it declines is not raised again.
## Severity
- 🔴 **must fix** — a goal, a principle or correctness broken. Fixed, or shown factually wrong; never declined.
- 🟡 **should fix** — worse than it needs to be. Fixed, or declined.
- 🟢 **nit** — fixed if cheap; never holds a pass.
- ❓ **question** for the author: a finding you could not confirm goes here, not above.
- 🔀 **escalation** — names the reviewer whose concern it is (`product-owner-reviewer`, `systems-architect` or `/security-review`) and why, in one line. The orchestrator runs it.
Other reviewers map onto this scale:
- `/security-review`: HIGH is 🔴, MEDIUM 🟡, LOW 🟢. A HIGH shown not real is recorded with what disproved it.
- A forge's auto-reviewer: what it marks blocking is 🔴.
## Verdict
A review's first line, derived from the findings:
- `BLOCK` — a 🔴 or a 🟡 stands.
- `APPROVE WITH NITS` — only 🟢 and ❓ remain.
- `APPROVE` — nothing remains.
## Rounds
- Surface everything in round 1.
- From round 2 the prompt carries the previous round's findings verbatim and what changed since. Verify each earlier 🔴 and 🟡 is resolved — re-run the scenario, never trust the claim — then review what changed. A fix raises a new finding only where the fix itself introduced a real problem.
- A pass is done on no 🔴 and no 🟡. The 🟢 and ❓ left are addressed in that round — fixed, answered, declined or filed in `todo.md` — and take no further round, unless a fix changes behaviour.
- Round cap: a pass runs at most three times per chunk, re-entries included. A fourth run lists what is open and asks the human.
## Declining
A 🟡 or below may be declined where the reason is sound, consistent with the goals, and confidence is very high. The decline, its reason and the goal it rests on go to `docs/decisions.md`, with the human's decisions and answers to ❓; an unrecorded one is asked again next review. A reason no goal speaks to is a gap in the goals, taken per `~/.claude/CLAUDE.md` → "Ask, don't guess" — or fix the finding. Never a silent drop, and never a decline argued from convenience or the size of the fix.
-38
View File
@@ -1,38 +0,0 @@
# Review protocol
Words: `~/.claude/CLAUDE.md` → "Vocabulary".
## Verdict
A review's first line, derived mechanically from the findings:
- `BLOCK` — a 🔴 stands; for a looping reviewer, a 🟡 too.
- `ALIGN` — systems-architect only: no 🔴, drift (🟡) to address soon.
- `APPROVE WITH NITS` — only 🟢 and ❓ remain; the author's call.
- `APPROVE` — nothing remains.
## Severity
- 🔴 **must fix.** Never declinable: it is fixed, or shown factually wrong.
- 🟡 **should fix.** Holds a looping reviewer at `BLOCK`, but may be declined.
- 🟢 **nit.** Never holds the loop.
- ❓ **question** for the author: a finding you could not confirm goes here, not above.
- 🔀 **escalation**: names the reviewer to run next (`product-owner-reviewer`, `systems-architect`, or the `security-review` skill) and a one-line reason. The caller runs it; it is never optional.
## Rounds
- Surface everything in one round.
- From round 2 the prompt carries the previous round's findings verbatim and what changed since. Verify each previous 🔴 and 🟡 is resolved — re-run the scenario, don't trust the claim — then pass over what changed. A fix spawns a new finding only where the fix itself introduced a real problem.
- The loop exits on no 🔴 and no 🟡. The 🟢 and ❓ left then are addressed in that same round — fixed, answered, declined or filed in `todo.md` — and trigger no further round. A nit whose fix changes behaviour is a fresh finding and takes a round.
- Round cap: 3; when it stops the loop, list what is open and ask the human.
- Systems-architect gets one scoped re-check; still `BLOCK` → ask the human.
## Declining
Anything below 🔴 the caller may decline where the reason is sound, sits consistently with the repo's goals, and confidence is very high; the decline, its reason and the goal it rests on go to `docs/decisions.md`. A reason that contradicts a goal, or that no goal speaks to and you are not confident in, is a gap in the goals, taken per `~/.claude/CLAUDE.md` → "Working loop", "Ask, don't guess" — or fix the finding. Never a silent drop, and never a decline argued from convenience or the size of the fix.
A reviewer honours an accepted risk in `docs/decisions.md` and a finding declined this way: it stays declined and is not raised again.
## Documenting decisions
Knowledge that outlives one review goes in the repo, never in a memory file, where `~/.claude/CLAUDE.md` → "Comments and documentation" and "Ask, don't guess" put its kind. Record only decisions the human made, declines made under Declining, and answers the human gives to ❓; an unrecorded answer gets asked again next review.
+9 -11
View File
@@ -5,11 +5,11 @@ description: Ship a work chunk through review to a merged PR; decisions land in
# larv-review — ship the chunk, review until clean, gate green, merge
You orchestrate, fix, and ship; the reviewer agents only report. Run every reviewer synchronously (`run_in_background: false`) — each step depends on the previous result. Watch CI in the foreground too: a headless run exits when the turn ends, and a background watcher or a scheduled wakeup dies with it. A reviewer's report is input to the next step; the turn runs on until §11. Architecture strictly before security, security before stability: line-level polish on code the architect wants restructured, or on a call the security pass will rewrite, is wasted work. A fix made in any pass is a change the passes before it in this order never saw; a pass it re-enters says so, and a re-entry is a new loop with its own round cap.
You orchestrate, fix, and ship; the reviewer agents only report. Run every reviewer synchronously (`run_in_background: false`) — each step depends on the previous result. Watch CI in the foreground too: a headless run exits when the turn ends, and a background watcher or a scheduled wakeup dies with it. A reviewer's report is input to the next step; the turn runs on until §11. Architecture strictly before security, security before stability: line-level polish on code the architect wants restructured, or on a call the security pass will rewrite, is wasted work. A fix made in any pass is a change the passes before it in this order never saw; a pass it re-enters says so.
**Forge-neutral.** Five PR operations recur below: read a PR's diff, open a draft PR, read check status, mark ready, merge. Resolve the tooling from the remote per `~/.claude/CLAUDE.md` → "Git, commits, and PRs"; on any other forge, achieve the same intents through its CLI or API — discover how rather than assuming. A forge without a native draft state gets the closest equivalent (a `WIP:`/`Draft:` title prefix); note any approximation in the summary.
Words: `~/.claude/CLAUDE.md` → "Vocabulary". Verdicts, severities, round caps, declining a finding and where decisions are recorded: ~/.claude/principles/review-protocol.md. Its Declining section also binds `/security-review` and the external reviewer in §9.
Words: `~/.claude/CLAUDE.md` → "Vocabulary". Severities, verdicts, rounds, the round cap and declining, for every reviewer: ~/.claude/principles/review-findings.md.
## 0. Preconditions
@@ -51,8 +51,7 @@ Launch **systems-architect**: review the system as a whole entered through this
- **Stage 0 questions returned** (goals/audience/horizon unrecorded): relay them to the user, record the answers where the agent expects them (README), re-run once. No user → skip the pass, carry the questions into the summary.
- **BLOCK** → the restructure precedes everything below. Confirm with the user first when it materially reshapes their PR; apply it; re-run systems-architect once, scoped to verifying its own findings. Still BLOCK → stop and ask the human.
- **ALIGN** → apply what is cheap now; ask the user about the rest — each item becomes a fix, a ticket, or a documented decision, never a silent drop.
- **APPROVE** / **APPROVE WITH NITS** → proceed; nits per the protocol's rounds.
- **APPROVE** / **APPROVE WITH NITS** → proceed; nits per the findings document's rounds.
### Comprehension floor (with every architecture pass)
@@ -63,8 +62,7 @@ Invoke the `comprehension-panel` skill's scoring run (`~/.claude/skills/comprehe
Run the built-in **`/security-review`** skill over the branch diff. It is the pass of record here: its value is a tuned exclusion list and a ≥0.8 confidence floor, which a hand-written reviewer would reproduce worse. A fix made in any pass after it re-enters it only where it opens a new untrusted-input boundary or touches authn/authz, secrets or crypto.
- **HIGH** → verify it is real, then fix it before this chunk ships: inside this chunk's blast radius it is fixed here, outside it on its own branch and PR with this chunk waiting behind it. Say which. A verified HIGH is never filed for later and never put to the human as a question. Verification showing it is not real is no decline but a disproof — record what disproved it, since a finding that is factually wrong needs no goal to reject.
- **MEDIUM** → fix in this chunk, under the protocol's Declining section.
- **LOW** → treat as a 🟢.
- **MEDIUM** → fix in this chunk, or decline.
- A **MEDIUM or LOW** outside this chunk's scope → a `todo.md` item per `~/.claude/CLAUDE.md` → "Todo items"; filing it is not fixing it.
**Escalate to a full scan** — the `claude-security` plugin (`/claude-security` → "Scan changes"), first-party and agent-verified — when the change touches authn/authz, secrets or crypto, a new untrusted-input boundary, or a new external surface. Same shape of judgment as §2's trigger: a signal with no record behind it, and a user reachable, is an ask. The plugin is not enabled by default; unavailable → say so in the summary rather than substituting a hand-rolled pass.
@@ -75,7 +73,7 @@ Run the built-in **`/security-review`** skill over the branch diff. It is the pa
A fix sent back here opens its loop with a round prompted with the fix's scope and why it changed.
1. Launch **stability-reviewer**, prompted per the protocol's rounds.
1. Launch **stability-reviewer**, prompted per the findings document's rounds.
2. Fix every 🔴 **and every 🟡** along its Fix guidance (delete > simplify > modify > add). Keep test changes and implementation changes separately reviewable. §8's gate verifies what the final round's nits changed.
3. Commit and push each round's fixes so CI feedback accumulates while the loop runs.
4. Carry any 🔀 product-owner escalation into §6.
@@ -84,9 +82,9 @@ A fix sent back here opens its loop with a round prompted with the fix's scope a
A 🔀 product-owner-reviewer escalation from any pass runs it, and so does a change to an external surface, a fix from any pass after it included. Neither → skip it, say so in the summary.
1. Launch **product-owner-reviewer** with the change and the external surface it touches — API, CLI, UI, error and deprecation text a consumer reads, README and docs an outside reader lands on — prompted per the protocol's rounds.
2. Apply what it asks for, under the protocol's Declining section. Its findings are about the consumer's experience (wording, discoverability, upgrade path, the edge case a persona hits), so the fix is as often a message or a doc as it is code.
3. Commit and push each round; it exits and caps per the protocol.
1. Launch **product-owner-reviewer** with the change and the external surface it touches — API, CLI, UI, error and deprecation text a consumer reads, README and docs an outside reader lands on — prompted per the findings document's rounds.
2. Apply what it asks for, under the findings document's Declining section. Its findings are about the consumer's experience (wording, discoverability, upgrade path, the edge case a persona hits), so the fix is as often a message or a doc as it is code.
3. Commit and push each round; it exits and caps per the findings document.
4. Approved having changed nothing → you are done here; there is nothing to re-verify.
5. Otherwise re-enter §5 over what this loop changed.
@@ -119,7 +117,7 @@ Marking the PR ready is what summons CodeRabbit and its kind, so this follows §
- Detect one from the repo — a reviewer's config file (`.coderabbit.yaml` and the like), or its comments on the repo's earlier PRs. None found → skip, say so.
- 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; a reviewer that arrives later is read the next time anyone visits the PR, never waited on twice.
- Its findings follow the protocol like every reviewer above — no more authority, and no less; anything it marks blocking is a 🔴. Fix → commit → push; a fix that changes behavior re-enters §5, then §8. Then wait up to **5 minutes** for its re-review of the new commit.
- Its findings follow the findings document like every reviewer above — no more authority, and no less; anything it marks blocking is a 🔴. Fix → commit → push; a fix that changes behavior re-enters §5, then §8. Then wait up to **5 minutes** for its re-review of the new commit.
## 10. Goal alignment, then merge
-1
View File
@@ -6,7 +6,6 @@
The rebuild lifts every dimension: each item below is one chunk on a worktree based on `origin/rebuild`, its PR into `rebuild`, until the last item merges `rebuild` into main. The sketches, the judges' verdicts and what to take from each: `~/code/claude-handoffs/claude-config_2026-09-28.md`.
- **Hold every reviewer to one findings document, `principles/review-findings.md`.** Severity, verdict, rounds with round 2 verifying each earlier finding, the per-chunk round cap, declining, and `/security-review`'s HIGH/MEDIUM/LOW mapped onto the scale; it replaces `principles/review-protocol.md`.
- **Rewrite larv-review around one pass table and one re-entry rule.** A trigger per pass, each stated only there; the re-entry paragraph classifies a fix by the widest thing it touches; forge neutrality, the draft PR, CI watched in the foreground, the comprehension floor, the auto-reviewer's waits and the goal-alignment check carried over.
- **Make the three reviewer agents pure reporters in the findings document's vocabulary.** Keep their names and checklists; remove every README- and decision-writing duty and every private severity or verdict scale.
- **Bring `CLAUDE.md` → "Vocabulary", the README and `docs/decisions.md` in line with the rebuild.** Trigger covers every pass, round cap counts per chunk, "looping reviewer" goes if the rule no longer needs it; superseded decisions leave the log.