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

/code-review:deep-review [flags] [pr-url-or-number]

Examples:

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

Specialist Panel

All are enabled unless excluded with -:

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

If a PR/MR URL or number was provided, parse it before checkout. Do not pass a raw URL as an ID:

1. GitHub URL (github.com/.../pull/N): set PLATFORM=github, OWNER, REPO, PR_NUMBER=N
2. GitLab URL (gitlab.com/.../-/merge_requests/N): set PLATFORM=gitlab, PROJECT (group/subgroup/repo path), MR_IID=N. Prefer OWNER/REPO only when the project path has exactly two segments
3. Bare integer: detect platform from git remote -v (GitHub → gh, GitLab → glab), then set PR_NUMBER or MR_IID. Derive OWNER/REPO or PROJECT from the matching remote URL

Check out locally (always quote shell arguments):

GitHub:

gh pr checkout "$PR_NUMBER" --repo "$OWNER/$REPO"

GitLab:

glab mr checkout "$MR_IID" --repo "$PROJECT"

If glab accepts the full MR URL as a single argument, that is also fine — but never treat the URL string as $MR_IID for flags that expect a numeric IID alone.

Hard failure on inaccessible PR/MR: If a PR/MR identifier was provided and checkout or metadata fetch fails (wrong URL, private repo, missing permissions, 404/403), error and exit immediately. Do not fall back to reviewing the current local branch — that silently reviews the wrong code.

Determine the base branch and remote:

1. If a PR/MR is known, use its base ref (gh pr view --json baseRefName or glab mr view --output json)
2. Discover remotes with git remote -v (do not hardcode origin/upstream). Prefer the remote whose fetch URL matches the PR/MR host and project; otherwise use the remote tracked by the current branch (git branch -vv), then any remaining remote
3. If a PR/MR is known, probe its target branch first on the matching remote and use it as $BASE_REMOTE/$BASE_BRANCH. Only fall back to probing main then master (git ls-remote --heads "$REMOTE" main master) when no target branch was provided or the target branch was not found

Fetch and compute the merge base:

git fetch "$BASE_REMOTE" "$BASE_BRANCH"
MERGE_BASE=$(git merge-base "$BASE_REMOTE/$BASE_BRANCH" HEAD)

If no base ref can be determined, error and exit.

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)

When reviewing a PR/MR, check for previous panel review comments:

GitHub:

gh pr view "$PR_NUMBER" --json comments --jq \
  '.comments[] | select(.body | contains("Generated by /deep-review") or contains("Generated by /code-review:deep-review")) | {createdAt, body}'

GitLab:

glab mr note list "$MR_IID" --repo "$PROJECT" 2>/dev/null \
  | rg -n "Generated by /(code-review:)?deep-review" || true

If prior panel reviews exist, extract their findings and pass them to all specialists and the arbiter as context. Specialists should:

• Note which prior findings have been addressed by subsequent commits
• Flag prior findings that remain unresolved
• Avoid re-raising issues that were already noted and resolved
• Call out any regressions — issues that were fixed but reappeared

Phase 2 — Dispatch Specialists

Each specialist has its own prompt in references/specialists/:

Append the findings JSON schema to each specialist prompt:

[
  {
    "file": "src/example.py",
    "line": 42,
    "severity": "BLOCKING",
    "title": "Short title",
    "body": "Description of the issue",
    "suggestion": "Recommended action or null",
    "reproducer_needed": true
  }
]

Severity values: BLOCKING | SUGGESTION | NOTE

If no issues found, return an empty array and state what was checked.

Parallel Mode (default)

Launch all enabled specialist sub-agents in a single message so they run concurrently, using the Agent tool with run_in_background: true.

Resolve specialist prompts from the skill directory (repository root relative): plugins/code-review/skills/deep-review/references/specialists/{specialist}.md. Do not use a bare references/specialists/... path — agents may not share the skill's working directory.

Each sub-agent gets:

• The prompt: "You are a {specialist}. Read plugins/code-review/skills/deep-review/references/specialists/{specialist}.md for your review instructions."
• The merge base ref
• The PR number or branch name being reviewed
• Any prior review findings (if detected in Step 1.4)
• The findings JSON schema above

Sub-agents have full read access to the locally checked-out codebase. They explore the code on their own — read files, grep, run git commands, etc.

Sub-agents MUST NOT modify any files, and MUST NOT run any remote-write git commands (git push, force-push variants, push to protected branches, or pushes to any remote). They are read-only reviewers.

Use subagent_type: "general-purpose". Do NOT set the model parameter.