Dispatching Code Review Subagents

Dispatching Code Review Subagents

Core principle: split review only when independent reviewers can produce better signal than one reviewer. The main agent routes work and synthesizes results; it does not duplicate the reviewers' full review.

Workflow

Execute these steps in order. Do not skip steps. Do not stop after synthesis.

Step 1: Scope       — Inspect diff, decide reviewer count and review lenses.
Step 2: Review      — Dispatch reviewer subagents in parallel.
Step 3: Synthesize  — Deduplicate findings, merge, spot gaps.
Step 4: Verify      — 4a: classify & plan; 4b: verify per 4a plan, produce report-ready fields; 4c: for subagent output only, confirm exists & sanity-check, filter rejected.
Step 5: Report      — Assemble verifier output into report table, no re-judgment.

When NOT to Use This Skill

• The diff is trivial (typo, missing import, single-line config) — review inline directly.
• No subagent dispatch capability is available.
• A single localized change with no cross-domain risk — one quick self-review suffices.

Review Baseline Gate

Before choosing reviewer count or lenses, identify the authoritative baseline for judging correctness: explicit requirements, specifications, contracts, established behavior, repository rules, or user decisions.

Ask whether correctness can be determined from that baseline without inventing unstated intent.

• If yes, include the relevant baseline in every reviewer brief.
• If no, mark the affected scope as Baseline Blocked, name the missing decision and its owner, and pause review for that scope.
• Do not ask reviewers to choose among multiple valid intended outcomes.

Decide Reviewer Count

One reviewer when the diff is small, localized, or owned by one domain. Multiple in parallel when the change spans independent domains, distinct lenses would produce different findings, or the diff is large enough that one reviewer would sample instead of inspect.

Use layered review only when one pass changes the next (e.g., correctness findings reshape how a second reviewer examines tests). If passes are independent, run in parallel.

Choose Review Lenses

Determine which perspectives produce the most valuable, non-overlapping findings. If two lenses would find the same issues, merge them. Each reviewer should have a mission no other covers.

Example lenses (adapt or invent as needed): architectural fit, correctness/contracts, concurrency/state, security, data integrity, test quality, performance, UX/product behavior.

The right number is the minimum that covers the risk surface. Avoid sending every reviewer the same generic prompt — duplicate prompts produce duplicate noise.

Main Agent Contract

The main agent owns: inspecting context to choose scopes/lenses, writing bounded prompts with explicit file paths and output format, running independent reviewers in parallel, deduplicating findings, calling out conflicts and gaps, and dispatching verification.

The main agent does not: re-review every line after subagents report, treat reviewer agreement as proof when both saw incomplete context, or stop after synthesis without verification.

Reviewer Prompt Shape

Use a concrete brief:

Review [files/area] for [theme/lens].
Prioritize bugs, regressions, and missing tests over style.
Return findings with file/line references, a short rationale, and an initial severity assessment (Critical/High/Medium/Low) based on the diff and available context.
Mention important gaps if the available context is insufficient.

Reviewers must give a grounded severity assessment, not vague hints.

Synthesis Output

Return one consolidated review:

• Merge duplicates under the strongest rationale.
• Preserve file/line references.
• Separate disagreements and missing context.
• Separate Baseline Gaps: concerns that require choosing the intended behavior rather than checking code against an explicit baseline. Do not assign them severity or send them to Step 4; route them to the owning decision process and resume the affected review scope only after the baseline is resolved.
• Keep cleanup suggestions non-blocking unless they create real risk.

Note: Preserve reviewer severity assessments through synthesis — they are grounded initial judgments, not placeholders. Verifier (Step 4b) re-checks against actual source code and may confirm or correct.

Verification Phase (Step 4)

Reviewers produce hypotheses, not facts. Verification is mandatory — "skip subagent dispatch" means verify inline (main agent reads cited code), not skip verification. The only trivial case: ALL findings self-evident from diff AND reviewer cited exact lines (typo, missing import) — even then, confirm each line.

Step 4a: Classify & Plan — HARD GATE

Produce the classification table below before any verification action. If you are reading source or dispatching verifiers without this table, STOP — go back and classify. Every finding must be classified; unclassified = unverified. Do not proceed to 4b until the table is complete.

Also tag: Packages (which to read) and Confidence (High if multiple reviewers agree, Low if single-source). Low-confidence findings must be verified.

Then decide verifier count (after classification): all Shallow → self-inline. Homogeneous Deep → one verifier batching all. Independent chains or mixed packages → split by package then by chain. If plan yields more verifiers than findings, merge — review was over-split upstream.

Write one split-rationale line:

Dispatching N verifier(s) [or "self-inline"]: V1 covers [packages/depth], V2 covers ...

Output the plan (gate artifact):

Step 4b: Dispatch & Verify

Each verifier reads actual source code (not the diff) and confirms or rejects each finding. The verifier's structured output is the direct input to the final report — it must produce report-ready fields, not just yes/no:

You are verifying code review findings. Read the actual source code and confirm each:
1. Does the issue actually exist? (cite exact file:line + code snippet)
2. How severe is the real-world impact? What scenario triggers it?

**Project root:** [path]

### Finding N: [title]
- **Claim:** [what the reviewer said]
- **Read:** [specific files to check]

**For each finding, return:**
- **Exists?** Yes / No / Uncertain (with exact code evidence or what's missing)
- **Severity** (if exists): Critical / High / Medium / Low
- **Impact** (if exists): trigger scenario + magnitude (1 sentence, e.g., "Network jitter causes repeated toast popups, blocking interaction for 10s+")
- **Fix Clarity** (if exists): Actionable (1-line fix description) / Needs Discussion (option A vs option B + key tradeoff)

If a verifier marks a finding Uncertain, you MAY dispatch one follow-up verifier scoped to that single finding only. At most one re-verification round. Do not re-dispatch the full batch.

Step 4c: Confirm & Filter

Review verifier output. The 4c path depends on 4a classification:

For Shallow (inline self-verified): Main agent already read source and produced Severity/Impact/Fix Clarity directly — no third-party output to sanity-check. Skip 4c confirmation; these findings go straight to Step 5.

For Deep (subagent verified): Review each verifier's structured output:

1. Exists? = No → Reject. List under "Rejected" with verifier's one-line rationale.
2. Exists? = Uncertain → Dispatch follow-up verifier per Step 4b rules. Do not report directly.
3. Exists? = Yes → Sanity-check the three fields:
   • Severity: Does it match the Impact description? Correct and note reason if clearly over/understated.
   • Impact: Is the scenario and magnitude verifiable? Reject or downgrade exaggerated or unsupported claims.
   • Fix Clarity: If Actionable, confirm the fix path is feasible. If Needs Discussion, confirm real tradeoffs exist (not just missing info).

4c is still verification logic for subagent output — judging whether findings are real and whether severity/impact hold up. It is not passive passthrough. Confirmed fields become Step 5 report input; Step 5 does not re-judge.

Step 5: Report (Reporting Phase)

Assemble 4c-confirmed output into the report table. Do not re-judge severity, impact, or fix clarity — 4c already confirmed these. Your job is to assemble, sort, and present.

Sort by severity (Critical → Low), then Fix Clarity (Actionable → Needs Discussion).

Rules:

• Issue: Factual description of what the problem is (no cause, no fix).
• Severity: 4c-confirmed Critical/High/Medium/Low.
• Impact: 4c-confirmed Impact, explains why this severity.
• Fix: 4c-confirmed Fix Clarity — prefix [Actionable] or [Needs Discussion]. Do not implement unless the user asks.
• Rejected findings: list separately as "Rejected" with one-line rationale.

This closes the workflow. Do not start another full review loop over findings unless the user requests it.

Rationalizations to Reject

Red Flags

Stop and resize when:

• Review setup takes longer than the review itself.
• Reviewers have overlapping generic missions.
• Main agent does a full independent review after receiving results.
• One small fix triggers another full review loop.
• Verification proceeds without the 4a table, or Deep findings are inline-verified by main agent.