Workflow: Parallel Code Review

Type: Review | Complexity: Medium | Team Size: 2-4 reviewers

Multi-Reviewer

Distribute code review across multiple independent reviewers, each focusing on different aspects (security, performance, test coverage, maintainability). Parallel analysis finds more issues faster than sequential review.

When to Use

• Complex PRs requiring multiple perspectives
• High-stakes changes that need thorough coverage
• Fast feedback when parallel review beats sequential
• Specialized knowledge needed (security, performance, tests)

When NOT to Use

• Small, straightforward changes (use single reviewer)
• Tight time deadlines and only one reviewer available
• Very interdependent concerns that need discussion
• Trivial typo fixes or style cleanups

Workflow Overview

Step-by-Step Guide

Step 1: Identify Review Dimensions

Determine what perspectives your PR needs:

• Security: Auth, data handling, injection risks
• Performance: Algorithms, database queries, caching
• Tests: Coverage, edge cases, integration tests
• Maintainability: Code clarity, documentation, patterns
• Accessibility: User-facing changes, keyboard nav, screen readers

Choose 2-4 key dimensions for your PR.

Step 2: Create Team with Specific Reviewers

Create an agent team to review PR #142. Spawn three reviewers:
- One security expert reviewing authentication changes
- One performance specialist analyzing database queries
- One test quality reviewer checking coverage

Claude will:

1. Spawn 3 teammates
2. Give each a specific focus
3. Point them to the PR code
4. Initialize shared task list

Step 3: Give Each Reviewer Their Focus

Make each reviewer's job clear:

Tell the security reviewer:
"This PR modifies JWT token handling. Focus on:
1. Token generation and validation
2. Secret key management
3. Refresh token security
4. Cross-site request forgery protection"

Tell the performance reviewer:
"Check database query efficiency:
1. Look for N+1 query patterns
2. Verify indexes are used
3. Check for unnecessary data fetching
4. Suggest caching opportunities"

Tell the test reviewer:
"Evaluate test coverage:
1. Are new functions tested?
2. Are edge cases covered?
3. Is integration tested?
4. Are error paths tested?"

Step 4: Monitor Parallel Reviews

Watch progress:

Show me the current status of all reviewers

Output might show:

Security Reviewer: Analyzing token generation (in progress)
Performance Reviewer: Examining database layer (in progress)
Test Reviewer: Checking test files (in progress)

Reviewers work independently without waiting.

Step 5: Collect Findings

As reviewers finish:

Collect all findings and compile into a comprehensive review report

Lead will:

1. Gather results from each reviewer
2. Identify overlaps and conflicts
3. Prioritize issues by severity
4. Create consolidated report

Step 6: Synthesize into Final Review

Create a summary review that combines all findings.
Use this format:

# Code Review Summary - PR #142

## Issues Found

### Critical (Must Fix)
[Summary of any critical issues]

### Important (Should Fix)
[Summary of important issues]

### Nice to Have (Consider)
[Suggestions for improvement]

## Approval Decision
[Approve / Request Changes / Comment]

Step 7: Clean Up

Clean up the team

Save review to PR comments or document.

Real-World Example

Scenario: AuthService Refactor

PR Description: Refactor authentication service to use JWT tokens with refresh token rotation strategy.

Reviewers Needed:

• Security specialist
• Performance analyst
• Test coverage reviewer

Team Creation:

Create an agent team to deeply review PR #89 for authentication refactoring.
Spawn 3 reviewers:
- Security Expert: "Review JWT implementation, token storage, and refresh strategy"
- Performance Specialist: "Analyze login endpoint speed and database queries"
- Test Coverage Reviewer: "Verify test coverage for auth flows and edge cases"

All reviewers should examine the same PR but focus on their specialty.
Parallelize to get all three perspectives faster than sequential review.

Expected Findings:

• Security: Token expiry handling, refresh chain vulnerabilities
• Performance: N+1 query in user lookup during token validation
• Tests: Missing coverage for refresh token expiry edge case

Lead Synthesis:

## PR #89 Code Review Summary

### Critical Issues
1. **Refresh token vulnerability** (Security)
   - Current implementation allows unlimited refresh chains
   - Recommendation: Add max refresh count or timestamp check

### Important Improvements
1. **N+1 query in login endpoint** (Performance)
   - User lookup happening in loop
   - Recommendation: Batch load or use JOIN

2. **Missing edge case tests** (Tests)
   - Refresh token expiry not tested
   - Recommendation: Add test for expired refresh token

### Approval
Conditional approval - address critical security issue first, then important optimizations.

Configuration Options

Reviewer Count

• 2 reviewers: Light review (speed-focused)

  Security + Tests OR Performance + Tests

• 3 reviewers: Balanced review (quality-focused)

  Security + Performance + Tests

• 4+ reviewers: Comprehensive review (thorough)

  Security + Performance + Tests + Maintainability

With Plan Approval

For risky changes, require reviewers to submit plans:

Create an agent team to review PR #142 with plan approval required.
Each reviewer must submit their review plan before detailed analysis.

Each reviewer creates plan like:

Review Plan:
1. Scan code structure
2. Identify high-risk areas
3. Deep dive into security implications
4. Check for common vulnerabilities
5. Document findings

Lead approves each plan before detailed review begins.

Verification Checklist

✓ All reviewers present

• Can cycle through all 3 (or N) reviewers
• Each has their focus area
• No duplicate expertise

✓ Reviews running in parallel

• All reviewers working simultaneously
• Not waiting on each other
• Independent progress

✓ Findings collected

• Each reviewer submitted results
• Lead can access all findings
• No lost analysis

✓ Synthesis complete

• Single consolidated report created
• Issues prioritized by severity
• Clear approval recommendation

✓ Team cleaned up

• Reviewed PR is marked reviewed
• Team resources freed
• Session ready for next review

Quality Improvements

Parallel review typically finds:

• 25-40% more issues than single reviewer
• Better coverage across multiple dimensions
• Faster turnaround (parallel time, not sequential)
• Reduced bias (multiple perspectives challenge each other)

Troubleshooting

Q: Reviewers finding conflicting issues A: This is normal! Lead's job is to synthesize. Different perspectives sometimes disagree - that's valuable.

Q: Review taking too long A:

1. Reduce reviewer count (2 vs 3)
2. Scope down PR (review smaller changes)
3. Use simpler team configuration

Q: One reviewer finds nothing, others find lots A:

1. This is expected - different things to find
2. Reassign reviewer if clearly ineffective
3. Give more specific focus to struggling reviewer

Q: Need to pause review mid-way A:

1. Tell reviewers: "Save your findings so far"
2. Clean up team normally
3. Create new team to finish later

Best Practices

Clear Specialization

Each reviewer has distinct, non-overlapping focus:

• ✓ Security, Performance, Tests (clear)
• ✗ Security, Authorization, Tests (overlapping)

Adequate Context

Give reviewers enough info:

Review src/auth/jwt-handler.ts in PR #89.
Our JWT strategy uses HS256 with 15-minute expiry.
Recent change adds refresh token rotation.

Balanced Scope

Make sure each reviewer gets roughly equal work:

• ✓ 500 lines, 3 reviewers ≈ 167 lines each
• ✗ 500 lines, 3 reviewers = one reviews 400 lines

Synthesis Timing

Synthesize as reviewers finish, not just at the end:

Tell me findings so far

This prevents losing details.

Performance Metrics

Track review effectiveness:

Metric	Baseline	With Parallel
Issues found	N	N + 25-40%
Review time	2 hours	0.5-1 hour
Total effort	2 hours	1.5 hours
Speedup	1x	2-4x faster

See Also

• SOP-002: Create Your First Team
• SOP-004: Spawn and Manage Teammates
• Competing Hypotheses Workflow
• Delegate Mode Workflow