Deep Review

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): Run each specialist as a dedicated sub-agent concurrently. This is thorough but expensive because each sub-agent independently derives its own view of the repository.
• Serial (--serial): Run all specialists inline in the main agent, one after another. This is significantly cheaper because the repository 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

Invoke deep-review with optional flags and a PR URL or number.

Examples:

• deep-review — all reviewers, review current branch
• deep-review --serial — cheaper serial mode
• deep-review -qa,-writer — skip QA and Technical Writer
• deep-review --comment 42 — review PR #42, post verdict as comment
• deep-review --coderabbit https://github.com/org/repository/pull/42
• deep-review https://gitlab.com/org/repository/-/merge_requests/7

Specialist Panel

All are enabled unless excluded with -:

Routing Topology

  bugs  adversarial  security  architecture  consistency  qa  writer  slopinator
    \_______|__________|__________|___________|___________|_____|_______/
                                  |
                            [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 and determine the round

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. Then apply the iterative review convergence policy to determine the round and its blocking-threshold multiplier. Round 1 uses the baseline threshold; later rounds use 2x, 4x, 8x, and continue doubling. Unresolved blockers from earlier rounds carry forward without requalifying against the higher threshold.

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. Give every specialist the review round, multiplier, prior findings, and the distinction between carried blockers and new candidates.

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).

1. Deduplicate — merge duplicates, keep strongest reproducer
2. Filter noise — remove false positives, style nitpicks, speculative findings, and issues already addressed in the branch
3. Resolve conflicts — corroboration strengthens. Unresolved adversarial blockers carry forward; new adversarial concerns must meet the current round's threshold
4. Assign disposition — APPROVE (no BLOCKING), REQUEST_CHANGES (BLOCKING findings), or NEEDS_DISCUSSION (needs author input). Biases: security over ergonomics, consistency over elegance, reproduced bugs that meet the applicable round threshold are BLOCKING, and unresolved reproduced blockers remain BLOCKING. Do not manufacture findings
5. Prioritize — reproduced security bugs > reproduced functional bugs > unreproduced > architecture > style/docs
6. Emit verdict — state the review round and multiplier, then 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 the deep-review skill</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

At round 1, a change passes when there are no unresolved functional bugs, unrefuted adversarial scenarios, unmitigated vulnerabilities or supply-chain risks, structural defects, duplicate helpers, material test gaps, documentation inconsistencies, or review residue and generated-sounding prose in shipped text, and the panel arbiter has ratified the disposition. On later rounds, those criteria still guide investigation, but only unresolved carried blockers and new findings that satisfy the current round's escalating threshold prevent approval. Keep below-threshold discoveries visible as suggestions or notes so convergence does not hide useful feedback.

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.