Hold every reviewer to one findings document
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user