| name | deep-review |
| description | Use when a deeper level of code review is requested. Multi-agent panel code review with specialist reviewers and forced runtime reproducers for all BLOCKING bug findings. Optionally posts to GitHub/GitLab as a PENDING review. |
| argument-hint | [--serial] [--comment] [--coderabbit] [--codex] [-reviewer,...] [pr-url-or-number] |
Deep Review — Multi-Specialist Panel Review with Reproducers
Review a branch's changes with parallel specialist subagent reviewers,
each examining the code through a different lens. Verify every bug
finding with a runtime reproducer. Optionally post to GitHub/GitLab
as a PENDING review.
No PR/MR is required — the review works on any branch with commits
ahead of its base.
Two execution modes:
- Parallel (default): Each specialist runs as a dedicated sub-agent
concurrently. Thorough but expensive — each sub-agent independently
derives its own view of the codebase.
- Serial (
--serial): All specialists run inline in the main agent,
one after another. Significantly cheaper because the codebase context
is derived once and shared across all specialists. Trade-off: reviews
run sequentially, and later specialists can see prior specialists'
findings (which may bias their analysis).
Arguments
/reviews:deep-review [flags] [pr-url-or-number]
| Argument | Description |
|---|
--serial | Run all specialists inline instead of as parallel sub-agents |
--comment | Post the verdict as a PR comment after review. Requires a PR identifier |
--coderabbit | Include CodeRabbit as an external reviewer |
--codex | Include OpenAI Codex as an external reviewer |
-reviewer | Exclude a specialist (e.g., -writer,-qa). All enabled by default |
| pr identifier | GitHub/GitLab PR URL or bare PR number. Optional |
Examples:
/reviews:deep-review — all reviewers, review current branch/reviews:deep-review --serial — cheaper serial mode/reviews:deep-review -qa,-writer — skip QA and Technical Writer/reviews:deep-review --comment 42 — review PR #42, post verdict as comment/reviews:deep-review --coderabbit https://github.com/org/repo/pull/42/reviews:deep-review https://gitlab.com/org/repo/-/merge_requests/7
Specialist Panel
All are enabled unless excluded with -:
| Specialist | Lens | Reproducer? |
|---|
| bugs | Functional bugs: missing calls, wrong logic, unhandled edge cases | Yes — mandatory |
| adversarial | Break the code: bad inputs, race conditions, boundary values | Yes — mandatory |
| security | Vulnerabilities, credential handling, dependency trust, supply chain integrity | When claiming a concrete exploit |
| architecture | Structural patterns, SOLID, cross-file impact, module boundaries | No |
| consistency | Duplicate helpers, convention drift, style match with existing code | No |
| qa | Test coverage gaps, missing edge-case tests, concrete test suggestions | No |
| writer | Documentation accuracy, staleness, consistency with code changes | No |
Routing Topology
bugs adversarial security architecture consistency qa writer
\_______|__________|__________|___________|___________|____|
|
[reproduce] ← bug/security findings only
|
v
panel-arbiter
(final call)
- Specialists raise findings independently — no implicit consensus.
Each runs as a separate sub-agent and cannot see the others' output.
- Reproducer agents verify bug/security claims before arbitration.
- Panel Arbiter synthesizes after all specialists and reproducers complete.
Procedure
Phase 1 — Setup
Step 1.1: Parse arguments
Split the argument string on whitespace. Flags (--serial,
--comment, --coderabbit, --codex) set modes. Tokens like
-writer,-qa exclude those specialists (validate against the
roster; unknown names warned and ignored). A PR URL or bare
integer is the PR identifier (for bare integers, detect platform
from git remote). Error if: all specialists excluded, --comment
without PR identifier, or multiple PR identifiers.
Step 1.2: Check out the PR and determine base ref
Follow references/setup.md: parse the PR/MR
URL into platform/project/id (never pass a raw URL as $MR_IID),
check out with quoted args, discover remotes via git remote -v,
and compute $MERGE_BASE.
If a PR/MR was specified and checkout/metadata fails, error and
exit — never fall back to reviewing the current local branch.
Step 1.3: Verify there are changes
Check that the branch has commits ahead of the base. If there are
no changes, stop: "No changes found between HEAD and the base
branch."
If a PR/MR exists, also fetch its description for context.
Step 1.4: Detect prior reviews (PR only)
Follow the GitHub/GitLab commands in
references/setup.md. Pass prior
Generated by /deep-review findings to specialists and the
arbiter so resolved items and regressions are handled.
Phase 2 — Dispatch Specialists
Each specialist prompt lives under
references/specialists/. Dispatch rules,
JSON schema, parallel/serial modes, and external reviewers are in
references/dispatch.md.
Phase 3 — Completeness Gate
After all sub-agents and external reviewers return, verify all
enabled specialists produced findings (or an explicit "no issues"
with what was checked). A valid empty JSON array [] with an
explanation of what was checked is success — do not retry it.
If any specialist returned an error or a missing/malformed result,
re-dispatch it once. If the retry also fails, record the
failure and proceed.
External reviewer failures are non-blocking — note the error and
continue.
Phase 4 — Reproduce
For every BLOCKING finding with reproducer_needed: true, launch
a reproducer subagent (up to 5 in parallel). See
references/reproducer-prompt.md
for the prompt template and result processing rules.
Phase 5 — Panel Arbiter
Perform synthesis directly in the main agent (not a sub-agent).
- Deduplicate — merge duplicates, keep strongest reproducer
- Filter noise — remove false positives, style nitpicks,
speculative findings, and issues already addressed in the branch
- Resolve conflicts — corroboration strengthens; adversarial
concerns are blocking unless concretely refuted
- Assign disposition — APPROVE (no BLOCKING), REQUEST_CHANGES
(BLOCKING findings), or NEEDS_DISCUSSION (needs author input).
Biases: security over ergonomics, consistency over elegance,
reproduced bugs are always BLOCKING, do not manufacture findings
- Prioritize — reproduced security bugs > reproduced functional
bugs > unreproduced > architecture > style/docs
- Emit verdict — use collapsible
<details> blocks for
specialist findings (each specialist collapsed with severity
counts). Sections: Disposition, Specialist Findings, Panel
Synthesis, Required Actions, Optional Follow-ups, Stats.
Footer: <sub>Generated by [/reviews:deep-review](https://github.com/stbenjam/claude-nine/tree/main/plugins/reviews/skills/deep-review)</sub>.
Include collapsible reproducer details for confirmed BLOCKING bugs.
Phase 6 — Post to PR (Optional)
When --comment was passed, follow
references/pr-posting.md to post the
verdict to the PR and optionally create inline review comments.
$OWNER, $REPO, $PR_NUMBER / $PROJECT, $MR_IID must already
be set from Step 1.2.
Quality Gates
A change passes when: no unresolved functional bugs, no unrefuted
adversarial scenarios, no unmitigated vulnerabilities or supply
chain risks, sound architecture, no duplicate helpers, adequate
test coverage, documentation consistent with changes, and the
panel arbiter has ratified the disposition.
Error Handling
gh/glab not authenticated: Review can still run on a
locally checked-out branch.- No PR exists: Skip Phase 6; the verdict is the deliverable.
- External tool not installed/timeout: Skip, warn, continue.
- Subagent timeout: Report which specialist timed out, continue.
- No changes: Stop — "No changes found."
- Inaccessible PR/MR: Stop with an error; do not review another
branch.
- Review creation fails (422): Delete only comment/review IDs
created by the current attempt, then retry. Never delete existing
reviewer comments from other runs or authors.
Guardrails
- Never submit a PR review without explicit user confirmation.
- Omit
"event" from the initial review creation payload so the
review stays PENDING.
- Review agents MUST NOT modify any files in the working tree.
- Never
git push, force-push, or push to protected branches
(main/master) or any other remote. Discover remotes with
git remote -v when needed for reads.
- Reproducers run in /tmp. Do not push reproducer files.
- Do not run destructive operations in reproducers.
- Cap at 30 inline PR comments. Overflow goes to the review body.
