Move the review protocol into principles/, beside the rules the reviewers already read
This commit was merged in pull request #81.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Claude Code configuration
|
||||
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `AGENTS.md` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` for what the reviewer agents hold every project to; `docs/` for decisions; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `statusline.sh`; `CHANGELOG.md` and `todo.md`; and the tools in `bin/`.
|
||||
My personal `~/.claude`, version controlled: `CLAUDE.md` and `AGENTS.md` for instructions, the words under `CLAUDE.md` → "Vocabulary"; `agents/` and `skills/`; `principles/` for what the reviewer agents hold every project and every review to; `docs/` for decisions; `settings.json` for the harness and `.claude/settings.json` for the harness inside this repo; `statusline.sh`; `CHANGELOG.md` and `todo.md`; and the tools in `bin/`.
|
||||
|
||||
## Goals
|
||||
|
||||
|
||||
@@ -48,7 +48,7 @@ Before anything else, **read the shared principles** at `~/.claude/principles/`.
|
||||
|
||||
## Your Output Format
|
||||
|
||||
Verdict, severities, rounds and declines: ~/.claude/agents/review-protocol.md. After the verdict:
|
||||
Verdict, severities, rounds and declines: ~/.claude/principles/review-protocol.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/agents/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-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.
|
||||
|
||||
@@ -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/agents/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-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:
|
||||
|
||||
### 🔴 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.
|
||||
@@ -172,4 +172,4 @@ For each finding:
|
||||
|
||||
## Documenting decisions
|
||||
|
||||
Per ~/.claude/agents/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-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.
|
||||
|
||||
@@ -164,7 +164,7 @@ 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/agents/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-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.
|
||||
|
||||
**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.
|
||||
|
||||
@@ -214,7 +214,7 @@ Respect documented deliberate deviations — a stated trade-off is a valid reaso
|
||||
|
||||
## Documenting decisions
|
||||
|
||||
Per ~/.claude/agents/review-protocol.md. What clears the bar here:
|
||||
Per ~/.claude/principles/review-protocol.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
|
||||
|
||||
@@ -9,7 +9,7 @@ You orchestrate, fix, and ship; the reviewer agents only report. Run every revie
|
||||
|
||||
**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/agents/review-protocol.md. Its Declining section also binds `/security-review` and the external reviewer in §10.
|
||||
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 §10.
|
||||
|
||||
## 0. Preconditions
|
||||
|
||||
|
||||
@@ -6,7 +6,6 @@ Ships when a four-seat scoring run puts every dimension and the overall at 7.0 o
|
||||
|
||||
Shape, 7.0:
|
||||
|
||||
- Move `agents/review-protocol.md` out of `agents/`, beside what binds to it.
|
||||
- Split `larv-review` §7 so a fix's re-entry reads without the whole skill open.
|
||||
- Keep the fits-in-a-head thresholds in one place in `agents/systems-architect.md`, today four.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user