soloscrum-define-code-review-process
Defines the standard code review pipeline run during /soloscrum:review, plus the rules for handling findings from each source.
Pipeline
A code review combines three complementary sources. The first two run in parallel; the third is a selection step that runs after them, because which perspectives apply depends on what the change turned out to be:
- CodeRabbit (
coderabbit review --plain --base main) — produces findings with its own severity classification:critical/major/minor/nitpick. - Multi-agent review — implemented via the
code-review:code-reviewslash command (N parallel Sonnet agents, each with a focused lens: security, architecture, bug scan, history, in-file rules, coverage gap). Produces free-text findings, scored 0–100 by a Haiku agent per the rubric in that command. - Review perspectives — the user's own accumulated judgements, stored machine-locally per
soloscrum-define-review-perspective. The first two sources are general; this one is what the user has specifically learned and does not want re-learned.
All three sources' findings are then consolidated into a single PR comment.
Applying review perspectives
Perspectives live at ~/.claude/review-perspectives/*/PERSPECTIVE.md and are selected, not loaded wholesale:
List the corpus's
name+descriptionpairs:skills/soloscrum-define-review-perspective/scripts/list-perspectives.shThe script reads only each file's frontmatter, so bodies are never loaded for perspectives that are not selected. Descriptions are written to be decidable on their own — that skill's description rules exist for this step.
Fallback: where no Bash surface is available, glob
~/.claude/review-perspectives/*/PERSPECTIVE.mdand read the frontmatter directly. This is the same selection on more expensive input, not a degraded one —agents/soloscrum-review.mddeclarestools: Read, Glob, Grep, so the fallback is currently the live path for that agent.Select the ones whose stated when matches this PR — its diff, the areas it touches, the kind of change it is. Respect a stated negative trigger.
Read the body of the selected perspectives only, and apply each as an additional review lens.
An empty or absent corpus is the normal starting state, not an error and not a warning. Skip the step and say nothing; a user who has collected no perspectives should not see this reported as a gap on every review.
When the corpus is not empty, report how many perspectives it holds and how many were selected, even when none were. A perspective whose trigger is too narrow to ever fire again is otherwise indistinguishable from one that is simply not relevant today — the corpus can rot silently, and this line is the only signal that would surface it.
Perspectives are collected via /soloscrum:collect-perspective.
Draft-window override for code-review:code-review
code-review:code-review ships with an eligibility check (its step 1) that skips PRs still in draft. In soloscrum, that check MUST be bypassed: the PR is intentionally in draft when /soloscrum:review runs, because the draft window is where the local quality gate fires (see soloscrum-define-pr-lifecycle, "Why a draft window exists"). Honouring the upstream skip here silently drops half the review pipeline and defeats the draft-window design.
When invoking code-review:code-review from the soloscrum review pipeline (i.e. from soloscrum-review-implementation step 3 or any caller of this skill):
- Treat
draftas eligible — proceed past step 1 as if the PR were ready. - All other eligibility checks (closed, automated, already reviewed by you) still apply.
If code-review:code-review later exposes an explicit override argument, prefer that argument; until then, this directive is the authoritative override for soloscrum's /soloscrum:review.
Finding Handling Rules
Severity and confidence scores are inputs to a per-item decision, never auto-skip filters. Every finding from either source goes through the same decision: fix it, or skip it with a stated reason. The only difference between the two sources is whether a pre-filter runs before the decision, to suppress hallucinated findings.
CodeRabbit findings — every finding is decided individually
- No pre-filter. Every CodeRabbit finding (any severity, including
nitpick) is surfaced and put to the same per-item decision below. - Severity from CodeRabbit is informational only — it tells you what kind of issue it is, not whether to skip. A
nitpickthat is in scope and correct is still worth fixing. - A silent drop based on severity is a process failure.
Agent-generated findings — pre-filter, then decide
- Each agent finding is scored 0–100 by a separate Haiku scoring agent (per the rubric in
code-review:code-review). - Pre-filter: drop findings with score < 80 (high false-positive rate from fresh agents).
- Surviving findings then go through the same per-item decision below.
Review-perspective findings — grounding requirement instead of a confidence score
The perspective itself is trusted: the user authored it and confirmed it when it was collected. A finding it produces is not — that finding was generated by an LLM reading a diff, the same mechanism the 80-confidence filter exists to guard. "The rule is sound" and "this instance of the rule is real" are different claims, and conflating them would give perspective findings more trust than agent findings while using the identical generation path.
So perspective findings take no confidence score, but they must be grounded:
- Every perspective finding cites the diff location (file and line, inside this PR's diff) and the specific check in the perspective body it instantiates.
- A finding that cannot cite both is discarded as unsupported — not skipped-with-reason, because there is nothing to decide on. Discarding here targets hallucinated instances specifically, rather than filtering by a score that would also drop correct low-confidence ones.
- Grounded findings then go through the same per-item decision as every other source. No severity or confidence threshold applies.
This is deliberately not the 80-confidence filter. That filter drops findings a scoring agent is unsure about, which for a perspective would mean discarding exactly the judgement the user collected it to preserve. The grounding requirement instead demands evidence, which a hallucinated instance cannot supply and a real one always can.
- Record which perspective produced each finding. A perspective that keeps producing skipped findings is miscalibrated — that signal is only visible if the attribution is kept.
The per-item decision
For every surfaced finding, choose one:
- Fix — when all of the following hold:
- The finding is in scope (see definition below)
- The suggestion is correct (it identifies a real issue and the proposed change addresses it)
- The fix is well-bounded (see definition below)
Even a
nitpickshould be fixed when these three hold and the cost is small.
- Skip with stated reason — when at least one of the following:
- Out of scope — track as a follow-up Issue and write the issue number in the skip note
- The suggestion is wrong or based on a misread of the diff (cite the specific misread)
- Conflicts with an explicit project convention (cite which one)
In scope means the finding touches code or behavior introduced or directly modified by this PR's diff. A finding that points to pre-existing code outside the diff is out of scope by default unless the PR explicitly intended to refactor it.
Well-bounded means the fix can be applied within files already touched by the PR (or trivially adjacent ones), without cascading into unrelated refactors that would balloon the diff.
Reasons that are not valid skip rationale:
- "It's a nitpick" / "minor severity" — severity is not a skip reason
- "Solo dev so I'll skip" without a specific argument — explain why solo-dev makes this finding inapplicable
- "I'll fix later" without a tracking link — convert to an Issue and reference it
Why two different thresholds
- CodeRabbit findings have already been filtered by the tool itself; its severity classification is informational, and even its lowest tier corresponds to documented patterns. Re-filtering by severity silently drops legitimate signal.
- Multi-agent reviewers spawn fresh per PR and are prone to inventing constraints, mis-citing rules, or flagging intentional changes. The 80-confidence pre-filter is calibrated for that noise. After the pre-filter, the decision is still per-item.
- Mixing the two — applying the agent confidence pre-filter to CodeRabbit output, or accepting agent findings below 80 because they "look plausible" — is the failure mode this skill exists to prevent.
- Review perspectives take neither filter. Applying the 80-confidence filter would discard exactly the judgements the user collected them to preserve; applying nothing would trust an LLM-generated instance because the rule behind it was authored deliberately. The grounding requirement above is the third answer: demand evidence rather than a score.
PR Comment Format
A single comment combining all three sources. Every surfaced finding records the action taken (fix or skip + reason) — agent and CodeRabbit rows use the same shape.
### Code review
#### CodeRabbit findings
1. <severity> <one-line description> — <action: fix | skip + reason>
<link to file with full SHA + line range>
#### Agent findings (≥80 confidence)
1. <one-line description> (<rule or rationale>) — <action: fix | skip + reason>
<link to file with full SHA + line range>
#### Review-perspective findings
1. <one-line description> (perspective: <name>) — <action: fix | skip + reason>
<link to file with full SHA + line range>
<corpus line: N perspectives available, M selected for this PR — omit entirely when N is 0>
#### Verdict
Pass | Pass with follow-ups | Fail
Verdict legend
- Pass — every surfaced finding was decided to fix and the fix has landed in this PR (or was already correct and no fix needed).
- Pass with follow-ups — every finding was decided, but one or more were skipped as out-of-scope and tracked as follow-up Issues. The PR is mergeable; the follow-ups exist as separate Issues.
- Fail — at least one finding identifies a real correctness, security, or DoD violation that has not been fixed and is not legitimately out of scope.
Consolidate across sources before posting. Perspectives deliberately encode the same class of judgement some multi-agent lenses already cover, so the same defect can arrive from two or three sources. Report it once, in the section of the source that described it best, listing the other sources that also raised it. Deciding the same finding independently in three places produces redundant noise at best and contradictory actions at worst.
If all sources produce zero findings to decide on (CodeRabbit "No findings ✔", no agent finding ≥80, and no perspective finding), post the canonical "No issues found" comment. Omit the perspective section entirely when the corpus is empty — an empty section reads as a missing step rather than an absent input.
Post-verdict actions
The verdict is the input to a defined sequence of next actions. The full lifecycle phases and the reversible-vs-irreversible autonomy classification live in soloscrum-define-pr-lifecycle; this section names the actions and cites that skill for autonomy.
| Verdict | Who acts next | Actions (in order) | Pre-confirm? |
|---|---|---|---|
| Pass | soloscrum-review |
(1) gh pr review --approve — falls through on self-approve refusal; the verdict comment posted per "PR Comment Format" above is the formal Pass record (2) tracker Subtask → done via soloscrum-tracker-{profile}-transition-state (3) wait for CI green via soloscrum-tracker-github-wait-for-pr-checks — non-SUCCESS/SKIPPED/NEUTRAL conclusions retroactively downgrade to Fail (follow Fail row, do not run remaining Pass steps) (4) gh pr ready (5) report the merge command to the user |
No — every step is reversible per soloscrum-define-pr-lifecycle |
| Pass with follow-ups | soloscrum-review |
(1) confirm a follow-up Issue exists for each out-of-scope skip and that its number appears in the skip note; create any missing ones (2) then identical to Pass | No — same reversibility |
| Fail | soloscrum-review → soloscrum-dev |
(1) post per-finding feedback on the PR (2) tracker Subtask → in-progress via soloscrum-tracker-{profile}-transition-state (3) leave the PR in draft — do not call gh pr ready (4) hand back to soloscrum-dev to address findings |
No for the review-side actions; the dev rework loop then re-enters this pipeline |
Notes on autonomy:
gh pr readyafter Pass / Pass with follow-ups is a reversible transition (gh pr ready --undo) and runs without pre-confirm. Pausing here to ask the user is the over-cautious failure mode that motivated this skill — seesoloscrum-define-pr-lifecyclefor the full classification.gh pr mergeis not in the table above. Merge is always user-gated; the agent stops after the last Pass step and surfaces the merge command for the user to run.- On Fail, the PR is intentionally left in draft so that the "needs more work" state is externally visible and GitHub-side auto-reviewers stay suppressed during rework.
- Step 1 (
gh pr review --approve) is expected to fail in solo-dev with "Can not approve your own pull request"; this is the default state, not an error condition. The verdict comment posted per "PR Comment Format" above is the formal Pass record, and the remaining Pass steps still run. Seesoloscrum-define-pr-lifecycle, "Self-approve refusal in solo-dev contexts" for the full contract and the try-and-fall-through implementation pattern. - Issue close is not in the table. The post-verdict sequence transitions the Subtask state to
donebut does not close any Issue. Closure happens at merge time via the PR body'sCloses #keyword and GitHub's auto-close; parent Issues whose closing event is missed are cleaned up by the/soloscrum:refinejanitor. Seesoloscrum-define-pr-lifecycle, "Issue close happens at merge". - CI red retroactively downgrades Pass to Fail. Step 3 of the Pass row (CI-green wait via
soloscrum-tracker-github-wait-for-pr-checks) is part of the Pass contract — promoting a ready PR with red checks is the failure mode that step exists to prevent. When the wait surfaces a non-SUCCESS/SKIPPED/NEUTRALconclusion, the agent posts the failed conclusions on the PR, reverts the Subtask toin-progress, and follows the Fail row from that point on — nogh pr ready, no merge-command surface. The verdict comment posted under "Pass" is followed by a follow-up comment recording the CI-driven downgrade.
When to run
- Triggered by
/soloscrum:reviewafter the PR has been created and thesoloscrum-reviewagent has completed DoD/AC verification. - May also be invoked ad-hoc on any branch via the
code-review:code-reviewskill — the same handling rules apply.
Skipping CodeRabbit
If coderabbit CLI is not installed or the user is not authenticated, skip its run and proceed with multi-agent only. Note the skip explicitly in the PR comment ("CodeRabbit unavailable in this environment, multi-agent only").
Notes
- CodeRabbit auth is per-user; the plugin assumes the user has run
coderabbit auth login. - This skill is profile-agnostic — the pipeline is the same regardless of
tracker_profile.