acaprino/multi-reviewer-patterns

Multi-Reviewer Patterns

Patterns for coordinating parallel code reviews across multiple quality dimensions, deduplicating findings, calibrating severity, and producing consolidated reports.

When to Use This Skill

• Organizing a multi-dimensional code review
• Deciding which review dimensions to assign
• Deduplicating findings from multiple reviewers
• Calibrating severity ratings consistently
• Producing a consolidated review report

Review Dimension Allocation

Available Dimensions

| Dimension | Focus | When to Include | | ----------------- | --------------------------------------- | ------------------------------------------- | | Security | Vulnerabilities, auth, input validation | Always for code handling user input or auth | | Performance | Query efficiency, memory, caching | When changing data access or hot paths | | Architecture | SOLID, coupling, patterns | For structural changes or new modules | | Testing | Coverage, quality, edge cases | When adding new functionality | | Accessibility | WCAG, ARIA, keyboard nav | For UI/frontend changes |

Recommended Combinations

| Scenario | Dimensions | | ---------------------- | -------------------------------------------- | | API endpoint changes | Security, Performance, Architecture | | Frontend component | Architecture, Testing, Accessibility | | Database migration | Performance, Architecture | | Authentication changes | Security, Testing | | Full feature review | Security, Performance, Architecture, Testing |

Context Sharing Pattern

When /team-review runs in pipeline mode (no --skip-interconnect), reviewers do not receive raw code only -- they receive two context artifacts produced in Phase 1:

1. Deep-dive output at .deep-dive/ (from deep-dive-analysis plugin): 01-structure.md, 02-interfaces.md, 05-risks.md, and optionally 03-flows.md, 04-semantics.md, 06-documentation.md, 07-final-report.md.
2. Interconnect map at .team-review/02-interconnect.md (from senior-review:semantic-interconnect-mapper): contracts (formal / structural / implicit), invariants, domain rules, assumptions (verified / documented / unverified), integration hot-spots, change impact radius.

Why context sharing matters

Without shared context, each reviewer re-reads the code from scratch. This is wasteful and, more importantly, blinds them to bugs that only manifest across components -- broken implicit contracts, invariant drift, bypass paths, non-idempotent retries, terminal state mutations. Phase 1 surfaces those concerns in the interconnect map, and Phase 2 reviewers use the map as a checklist.

How reviewers should consume the context

Reviewers should not read the entire context file. They should Grep or read only the anchors relevant to their dimension, guided by the ## Reviewer Hints section at the bottom of .team-review/02-interconnect.md.

Default anchor routing:

| Reviewer dimension | Primary anchors in interconnect map | |--------------------|-------------------------------------| | security | ## Integration Hot-Spots (inbound), ## Assumptions (unverified), ## Contracts (implicit, input validation) | | architecture (code-auditor) | ## Invariants, ## Contracts (structural + implicit), ## Call Graph | | logic-integrity | ## Contracts (implicit, unverified), ## Invariants, ## Assumptions (unverified), ## Domain Rules | | distributed-flows | ## Integration Hot-Spots (HTTP / queue / IPC), ## Call Graph (cross-service) | | chicken-egg | ## Assumptions (initialization order), ## Integration Hot-Spots (Env / config), ## Invariants (cross-component) | | ui-races | ## Invariants (temporal), ## Integration Hot-Spots (UI state) | | api-contracts (future) | ## Contracts (formal) |

Prompt template for context-aware reviewers

You are reviewing for the {dimension} dimension.

## Target
[...]

## Diff
[...]

## Context files
- Deep-dive output: .deep-dive/
- Interconnect map: .team-review/02-interconnect.md

Per `## Reviewer Hints` in the interconnect map, focus your reading on these anchors:
{anchors-for-this-dimension}

## Instructions
Follow your agent definition's phases and output format. Cite file:line for every finding.
Every finding that relates to a contract/invariant/assumption in the interconnect map should
also cite the map anchor that surfaced the concern.

Write your output to .team-review/findings-{dimension}.md.

Quality metric: context utilization rate

A useful quality signal at the end of a review: what fraction of findings cite an interconnect-map anchor?

• High (>= 30%): reviewers are leveraging the context effectively; the pipeline is paying off.
• Medium (10-30%): context used but inconsistently; consider refining prompts.
• Low (< 10%): either reviewers are ignoring the map or the map is too generic to be actionable.

The logic-integrity-auditor dimension should be at >= 70% (its findings are almost entirely driven by the map).

Fallback: --skip-interconnect mode

When the pipeline is skipped, reviewers receive only target + diff. In this mode:

• logic-integrity-auditor is not spawned (no map to drive it).
• All other reviewers fall back to their pre-pipeline behavior.
• No .deep-dive/ or .team-review/02-interconnect.md references should appear in reviewer prompts.

Pipeline Conventions (per reviewer)

Every reviewer agent that runs as part of /team-review Phase 2 carries a ## Pipeline Conventions section in its system prompt with four cross-cutting rules. The orchestrator does not need to repeat them in the spawn prompt, but should be aware of what they mandate:

• Scope budget: each reviewer stops after ~15 file reads without a finding and returns a "scope-off-topic" report. The orchestrator should plan targets at a granularity that respects this budget.
• No-findings protocol: reviewers may legitimately return "examined X, Y, Z -- no issues" instead of inventing findings. Treat such reports as valid Phase 3 input, not failure.
• Cross-Reviewer Notes: reviewers append observations that belong to other dimensions in a ## Cross-Reviewer Notes section. Phase 3 consolidation must scan for this section and route the observations to the appropriate reviewer (or surface them in the consolidated report under the recipient dimension).
• Interconnect anchor citation: reviewers cite map anchors when applicable. This is the same signal as the context utilization rate above; the section below quantifies the quality metric.

Reference: docs/references/agent-teams-best-practices.md § Pipeline Conventions.

Finding Deduplication

When multiple reviewers report issues at the same location:

Merge Rules

1. Same file:line, same issue -- Merge into one finding, credit all reviewers
2. Same file:line, different issues -- Keep as separate findings
3. Same issue, different locations -- Keep separate but cross-reference
4. Conflicting severity -- Use the higher severity rating
5. Conflicting recommendations -- Include both with reviewer attribution

Deduplication Process

For each finding in all reviewer reports:
  1. Check if another finding references the same file:line
  2. If yes, check if they describe the same issue
  3. If same issue: merge, keeping the more detailed description
  4. If different issue: keep both, tag as "co-located"
  5. Use highest severity among merged findings

Severity Calibration

Severity Criteria

| Severity | Impact | Likelihood | Examples | | ------------ | --------------------------------------------- | ---------------------- | -------------------------------------------- | | Critical | Data loss, security breach, complete failure | Certain or very likely | SQL injection, auth bypass, data corruption | | High | Significant functionality impact, degradation | Likely | Memory leak, missing validation, broken flow | | Medium | Partial impact, workaround exists | Possible | N+1 query, missing edge case, unclear error | | Low | Minimal impact, cosmetic | Unlikely | Style issue, minor optimization, naming |

Calibration Rules

• Security vulnerabilities exploitable by external users: always Critical or High
• Performance issues in hot paths: at least Medium
• Missing tests for critical paths: at least Medium
• Accessibility violations for core functionality: at least Medium
• Code style issues with no functional impact: Low

Consolidated Report Template

## Code Review Report

**Target**: {files/PR/directory}
**Reviewers**: {dimension-1}, {dimension-2}, {dimension-3}
**Date**: {date}
**Files Reviewed**: {count}

### Critical Findings ({count})

#### [CR-001] {Title}

**Location**: `{file}:{line}`
**Dimension**: {Security/Performance/etc.}
**Description**: {what was found}
**Impact**: {what could happen}
**Fix**: {recommended remediation}

### High Findings ({count})

...

### Medium Findings ({count})

...

### Low Findings ({count})

...

### Summary

| Dimension    | Critical | High  | Medium | Low   | Total  |
| ------------ | -------- | ----- | ------ | ----- | ------ |
| Security     | 1        | 2     | 3      | 0     | 6      |
| Performance  | 0        | 1     | 4      | 2     | 7      |
| Architecture | 0        | 0     | 2      | 3     | 5      |
| **Total**    | **1**    | **3** | **9**  | **5** | **18** |

### Recommendation

{Overall assessment and prioritized action items}

Adversarial Verification Panel

After findings are consolidated (deduplicated), each selected finding is judged by a panel of 3 verifiers run in parallel, each with a distinct lens. This replaces single-judge validation: three independent mandates catch more failure modes than three identical refuters.

This section is the source of truth. /agent-teams:team-review (Phase 4b) and /senior-review:code-review (Step 4b) both drive the panel from here.

The three lenses

Spawn one Agent per lens per finding. Use subagent_type: general-purpose. Use model: opus for lenses 1 and 2 (reasoning-heavy), model: sonnet for lens 3 (calibration). Run all three (and across findings) in parallel via run_in_background: true.

Lens 1 prompt (Reachability / Correctness):

You are verifier LENS 1 of 3 (Reachability / Correctness) for one code-review finding.
Your job: determine whether the described defect REALLY exists and is reachable.

## The Finding
[severity, file:line, description, suggested fix]

## The Diff
[diff for the relevant file]

## Full File Content
[full content of the file containing the finding]

## Instructions
1. Locate the exact file:line. Is the citation correct?
2. Trace the control/data flow: is the buggy path actually reachable in normal or error execution?
3. Does the code truly exhibit the described problem, or is the description a misread?
Return REAL only if you can point to the concrete lines and the path that triggers the defect.

Respond with EXACTLY:
- Verdict: REAL or FALSE_POSITIVE
- Confidence: 0-100
- Reason: 1-2 sentences citing file:line

Lens 2 prompt (False-Positive Causes):

You are verifier LENS 2 of 3 (False-Positive Causes) for one code-review finding.
Your job: actively try to REFUTE the finding. Default to FALSE_POSITIVE if uncertain.

## The Finding
[severity, file:line, description, suggested fix]

## The Diff
[diff for the relevant file]

## Full File Content
[full content of the file containing the finding]

## Instructions
Try to explain the flagged code away as one of:
1. Framework convention (Django/FastAPI/pytest/etc. idiom that is correct by design)
2. Intentional design choice consistent with surrounding code or CLAUDE.md
3. Pre-existing code not introduced or made newly relevant by the diff
4. A misunderstanding of the code's actual behavior or context
Return REAL only if the finding survives refutation on all four counts.

Respond with EXACTLY:
- Verdict: REAL or FALSE_POSITIVE
- Confidence: 0-100
- Reason: 1-2 sentences citing file:line; if FALSE_POSITIVE, name the refutation category

Lens 3 prompt (Severity Calibration):

You are verifier LENS 3 of 3 (Severity Calibration) for one code-review finding.
Assume the finding is REAL. Your only job is to vote the correct severity.

## The Finding
[severity, file:line, description, suggested fix]

## The Diff
[diff for the relevant file]

## Full File Content
[full content of the file containing the finding]

## Calibration criteria
- Critical: data loss, security breach, complete failure; certain or very likely
- High: significant functionality impact or degradation; likely
- Medium: partial impact, workaround exists; possible
- Low: minimal or cosmetic; unlikely

Respond with EXACTLY:
- Verdict: REAL
- Severity_vote: Critical or High or Medium or Low
- Confidence: 0-100
- Reason: 1-2 sentences citing file:line

Verdict schema

Each verifier returns: verdict (REAL or FALSE_POSITIVE; lens 3 always REAL), confidence (0-100), severity_vote (lens 3 only), reason (with a file:line citation).

Survival rule

• A finding survives if at least 2 of lenses 1-2 vote REAL.
• If >= 2 of lenses 1-2 vote FALSE_POSITIVE, the finding is discarded and counted as filtered (never silently dropped: the count appears in the report).
• Tie or inconclusive (1 REAL / 1 FALSE on lenses 1-2, or fewer than 2 valid verdicts returned) means the finding survives, marked contested. A flagged false positive is cheaper than a killed real bug.
• Final severity = lens-3 severity_vote when the finding is confirmed real; otherwise the original reviewer severity.

Fail-open

If a verifier errors or returns a malformed verdict, treat it as an abstention. If fewer than 2 valid verdicts return for a finding, apply the tie rule (survives, contested). The panel never crashes the pipeline and never silently drops a finding.

Selection: what enters the panel

• Normal (default-on): every finding with confidence >= 50% that survived deduplication, regardless of severity.
• Under cost guard (more than 25 surviving findings AND --rigorous not set): narrow to stakes + uncertainty band, which is all Critical/High findings plus any Medium/Low in the 50-75% confidence band or with a severity that conflicted between reviewers. The remaining findings pass through unverified, tagged unverified (cost-guard). Declare the narrowing in the report.
• --rigorous: ignore the cap; verify everything above the floor.
• --fast: skip the entire gate (panel + critic).

Cost guard is a finding-count proxy

In the prose/Agent substrate there is no token-budget API. The guard triggers on the number of surviving findings (threshold 25), not on real token consumption. State this wherever the guard is documented so no false precision is implied.

Completeness Critic

After verification, one critic agent asks what the review failed to cover. It turns blind spots from passive side effects into active output and, when warranted, into one more round of work.

This section is the source of truth. /agent-teams:team-review (Phase 4c) and /senior-review:code-review (Step 4c) both drive the critic from here.

Inputs

The critic reads: the verified findings, the review scope, the list of dimensions that ran, and whatever context exists (deep-dive output and the interconnect map for team-review; .deep-dive/ if present for code-review).

Gap taxonomy

The critic evaluates coverage against a fixed taxonomy and writes a ## Coverage Gaps block:

1. Dimensions not run that the scope warranted (e.g. security skipped on auth code; no distributed-flows despite messaging signals).
2. Files in scope cited by no reviewer (cross-check the changed-file list against files referenced in findings).
3. Unverified assumptions in the interconnect map that no finding addressed.
4. High-risk hot-spots (from deep-dive 05-risks.md or the map's Integration Hot-Spots) with zero findings.

Critic prompt

You are the completeness critic for a multi-dimensional code review. Your job is NOT
to find new bugs directly. It is to find what the review did not examine.

## Verified findings
[the consolidated, verified findings]

## Scope
[changed files / target]

## Dimensions that ran
[list]

## Context available
[deep-dive paths and interconnect map path, or "none"]

## Instructions
Produce a "## Coverage Gaps" list across these categories, each item actionable and specific:
1. Dimensions warranted by the scope but not run
2. In-scope files cited by no finding
3. Interconnect-map assumptions marked unverified that no finding addressed
4. High-risk hot-spots (05-risks.md / Integration Hot-Spots) with zero findings

Then, if and ONLY if one gap is a high-risk uncovered area, name the single most valuable
follow-up: which dimension/agent should review which files. Output it under
"## Recommended follow-up" with one entry, or "## Recommended follow-up: none".

Bounded follow-up round

If the critic names a high-risk uncovered area, spawn one targeted reviewer (the most specialized agent for that area) for a single round. Its findings re-enter deduplication and then the verification panel. One round only: the critic does not run again on the follow-up output.

Degradation

Under the cost guard or budget pressure, the critic degrades to report-only: it emits the ## Coverage Gaps list with no follow-up spawn, and the report states that the follow-up was skipped. --fast skips the critic entirely.