when-reviewing-pull-request-orchestrate-comprehensive-code-revie

name	when-reviewing-pull-request-orchestrate-comprehensive-code-revie
type	sop-workflow
description	Use when conducting comprehensive code review for pull requests across multiple quality dimensions. Orchestrates 12-15 specialized reviewer agents across 4 phases using star topology coordination. Covers automated checks, parallel specialized reviews (quality, security, performance, architecture, documentation), integration analysis, and final merge recommendation in a 4-hour workflow.
agents	["pr-manager","code-analyzer","security-manager","performance-analyzer","system-architect","api-documentation-specialist","tester","qa-engineer","devops-engineer","style-auditor","dependency-analyzer","test-coverage-reviewer","documentation-reviewer","system-integrator","code-reviewer"]
phases	4
memory_pattern	code-review/{pr-id}/phase-{N}/{reviewer}/{findings}

Code Review Orchestration Workflow

Comprehensive code review workflow orchestrating 12-15 specialized reviewers across automated checks, parallel expert reviews, integration analysis, and final approval recommendation. Designed for thorough quality validation across security, performance, architecture, testing, and documentation dimensions in a systematic 4-hour process.

Overview

This SOP implements a multi-dimensional code review process using star topology coordination where a central PR manager orchestrates specialized reviewers operating in parallel. The workflow emphasizes both thoroughness and efficiency by running automated checks first (gate 1), then parallelizing specialized human-centric reviews, followed by integration impact analysis, and finally synthesizing all findings into actionable recommendations.

The star pattern enables each specialist to focus deeply on their domain while the coordinator ensures comprehensive coverage and prevents conflicting feedback. Memory coordination allows reviewers to reference findings from other specialists, creating a holistic review experience.

Trigger Conditions

Use this workflow when:

• Reviewing pull requests requiring comprehensive quality validation
• Changes span multiple quality dimensions (code, security, performance, architecture)
• Need systematic review from multiple specialist perspectives
• PR introduces significant functionality or architectural changes
• Merge decision requires evidence-based go/no-go recommendation
• Team wants consistent, repeatable review process
• Code review SLA is within 4 hours (business hours)

Orchestrated Agents (15 Total)

Coordination Agent

• pr-manager - PR coordination, review orchestration, findings aggregation, author notification

Automated Check Agents (Phase 1)

• code-analyzer - Linting, static analysis, code complexity metrics
• tester - Test execution, test suite validation
• qa-engineer - Coverage analysis, test quality assessment

Specialized Review Agents (Phase 2)

• code-analyzer - Code quality, readability, maintainability, DRY, SOLID principles
• security-manager - Security vulnerabilities, OWASP compliance, secrets scanning, auth/auth
• performance-analyzer - Performance regressions, algorithmic efficiency, resource optimization
• system-architect - Architectural consistency, design patterns, scalability, integration fit
• api-documentation-specialist - Code documentation, API docs, comments, examples
• style-auditor - Code style consistency, formatting standards
• dependency-analyzer - Dependency audit, outdated packages, security vulnerabilities
• test-coverage-reviewer - Coverage metrics, uncovered code paths, edge case testing
• documentation-reviewer - README updates, changelog, migration guides

Integration Analysis Agents (Phase 3)

• system-integrator - Integration impact, breaking changes, backward compatibility
• devops-engineer - Deployment impact, infrastructure changes, rollback planning
• code-reviewer - Risk assessment, blast radius analysis

Workflow Phases

Phase 1: Automated Checks (30 Minutes, Parallel Gate)

Duration: 30 minutes Execution Mode: Parallel automated validation (fast fail-fast gate) Agents: code-analyzer, tester, qa-engineer, pr-manager

Process:

1. Initialize Review Swarm

   PR_ID="$1"  # e.g., "repo-name/pulls/123"
   PR_NUMBER=$(echo $PR_ID | cut -d'/' -f3)
   
   npx claude-flow hooks pre-task --description "Code review: PR #${PR_NUMBER}"
   npx claude-flow swarm init --topology star --max-agents 15 --strategy specialized
   npx claude-flow agent spawn --type pr-manager
   

   PR Manager retrieves PR metadata:

   • Changed files and line counts
   • Commit history and messages
   • Branch comparison (base vs head)
   • PR description and labels
   • Author and reviewers assigned

   Memory Storage:

   npx claude-flow memory store --key "code-review/${PR_ID}/metadata" \
     --value '{"pr_number": "'"${PR_NUMBER}"'", "files_changed": 15, "lines_added": 342, "lines_deleted": 78}'
   

2. Run Automated Checks in Parallel

   npx claude-flow task orchestrate --strategy parallel --max-agents 4
   

   Spawn all automated check agents concurrently:

   Linting Check (Code Analyzer):

   npx claude-flow agent spawn --type code-analyzer --focus "linting"
   
   # Run linting
   npm run lint  # ESLint for JS/TS
   # or
   pylint src/  # Python
   # or
   rubocop  # Ruby
   

   Checks:

   • Code style violations (max line length, indentation)
   • Unused variables and imports
   • Type errors (TypeScript)
   • Deprecated API usage
   • Code complexity warnings

   Memory Pattern:

Outputs:

• Automated check results (pass/fail for each)
• Test execution report
• Coverage report with delta
• Build status

Success Criteria:

• All linting checks passing
• All tests passing (100% of test suite)
• Code coverage meets thresholds
• Build successful with no errors

---

Phase 2: Specialized Reviews (2 Hours, Parallel Expert Analysis)

Duration: 2 hours Execution Mode: Parallel specialized reviews coordinated by PR manager Agents: 10 specialist reviewers

Process:

1. Initialize Specialist Review Swarm

   npx claude-flow task orchestrate --strategy parallel --max-agents 10 --priority high
   

2. Spawn All Specialist Reviewers Concurrently

   Each specialist reviews the PR from their domain expertise:

   Code Quality Review (Code Analyzer):

   npx claude-flow agent spawn --type code-analyzer --focus "code-quality"
   

   Reviews:

   • Readability: Clear names, appropriate function length, logical organization, cognitive complexity
   • Maintainability: DRY principle, SOLID principles, separation of concerns, error handling
   • Best Practices: Language idioms, design patterns, appropriate comments, no code smells

   Rating: 1-5 stars

   Findings Format:

   {
     "category": "code_quality",
     "findings": [
       {
         "severity": "MEDIUM",
         "file": "src/utils/parser.ts",
         "line": 45,
         "issue": "Function 'parseData' has cognitive complexity of 15 (max 10)",
         "suggestion": "Extract nested conditionals into separate validation functions"
       }
     ],
      
      
   
   

Outputs:

• 10 specialized review reports
• Aggregated findings with severity prioritization
• Blocking issues list
• Recommendations summary

Success Criteria:

• All specialist reviews completed
• Findings categorized by severity
• Blocking issues clearly identified
• Recommendations actionable and specific

---

Phase 3: Integration Analysis (1 Hour, Sequential Impact Assessment)

Duration: 1 hour Execution Mode: Sequential end-to-end impact analysis Agents: tester, devops-engineer, product-manager, code-reviewer

Process:

1. Integration Testing

   npx claude-flow agent spawn --type tester --focus "integration-impact"
   

   QA Engineer tests:

   • Does this change break existing functionality?
   • Are all integration tests passing?
   • Does it integrate properly with related modules?
   • Any unexpected side effects or regressions?

   Run integration test suite:

   npm run test:integration
   

   Findings:

   • Integration tests: 45/45 passing
   • No regressions detected
   • New functionality integrates cleanly

   Memory Pattern: code-review/${PR_ID}/phase-3/tester/integration-tests

2. Deployment Impact Assessment

   npx claude-flow memory retrieve --key "code-review/${PR_ID}/metadata"
   npx claude-flow agent spawn --type cicd-engineer --focus "deployment-impact"
   

   DevOps Engineer evaluates:

   • Infrastructure changes needed? (new services, scaling)
   • Database migrations required? (schema changes)
   • Configuration updates needed? (env vars, secrets)
   • Backward compatibility maintained? (can rollback safely)
   • Rollback plan clear and tested?

   Findings:

   {
     "infrastructure_changes": ["Add Redis cache for session storage"],
     "database_migrations": ["Add index on users.email for faster lookups"],
     "config_updates": 
      
      
      
   
   

Outputs:

• Integration test results
• Deployment impact report
• User impact assessment
• Risk analysis with mitigation recommendations

Success Criteria:

• Integration tests passing
• Deployment plan documented
• User impact understood
• Risk assessment complete with mitigation

---

Phase 4: Final Approval (30 Minutes, Decision & Notification)

Duration: 30 minutes Execution Mode: Sequential synthesis and decision Agents: pr-manager

Process:

1. Generate Final Review Summary

   npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/**"
   npx claude-flow agent spawn --type pr-manager --focus "final-summary"
   

   PR Manager synthesizes all phases:

   Summary Report:

   # Code Review Summary: PR #${PR_NUMBER}
   
   ## Automated Checks ✅
   - Linting: ✅ PASS (0 violations)
   - Tests: ✅ PASS (142/142 passing)
   - Coverage: ✅ PASS (93.5%, +2.3% delta)
   - Build: ✅ PASS (clean build, no warnings)
   
   ## Specialized Reviews
   - **Code Quality**: 4/5 stars (Good quality, minor improvements suggested)
   - **Security**: ⚠️ 1 HIGH issue (SQL injection risk in user query)
   - **Performance**: ⚠️ 1 HIGH impact (N+1 query problem)
   - **Architecture**: ⚠️ 1 MAJOR concern (tight coupling to payment provider)
   - **Documentation**: 75% complete (missing API docs + changelog)
   
   ## Integration Analysis
   - **Integration Tests**: ✅ All passing (45/45)
   - **Deployment Impact**: MEDIUM risk (requires Redis + DB migration)
   - **User Impact**: POSITIVE (new export feature)
   - **Risk Level**: MEDIUM (feature flag recommended)
   
   ## Blocking Issues (MUST FIX)
   1. [HIGH/SECURITY] SQL injection risk in src/api/users.ts:78
   2. [HIGH/PERFORMANCE] N+1 query in src/services/user-service.ts:125
   
   ## High-Priority Recommendations (SHOULD FIX)
   3. [MAJOR/ARCHITECTURE] Decouple payment service from Stripe SDK
   4. [MEDIUM/DOCUMENTATION] Add API documentation for webhook endpoint
   5. [MEDIUM/DEPLOYMENT] Add feature flag for gradual rollout
   
   ## Overall Decision: ⏸️ REQUEST CHANGES
   
   **Rationale**: Code is high quality overall, but 2 blocking issues (security + performance) must be addressed before merge. Once fixed, this PR will be ready for production.
   
   **Next Steps**:
   1. Author fixes blocking issues (estimated 2-4 hours)
   2. Re-run automated checks + security/performance reviews
   3. Once green, approve for merge with feature flag enabled
   

   Memory Storage:

   npx claude-flow memory store --key "code-review/${PR_ID}/phase-4/final-summary" \
     --value 
   

Outputs:

• Final review summary (comprehensive report)
• Merge decision (Approve/Request Changes/Reject)
• Author notification (GitHub comment)
• GitHub labels and status updated

Success Criteria:

• Final summary generated and comprehensive
• Decision clear and justified
• Author notified with actionable feedback
• GitHub PR status updated appropriately

---

Memory Coordination

Namespace Convention

All review data follows this hierarchical pattern:

code-review/{pr-id}/phase-{N}/{reviewer-type}/{findings-type}

Examples:

• code-review/repo/pulls/123/metadata
• code-review/repo/pulls/123/phase-1/code-analyzer/lint-results
• code-review/repo/pulls/123/phase-2/security-manager/security-review
• code-review/repo/pulls/123/phase-3/devops-engineer/deployment-impact
• code-review/repo/pulls/123/phase-4/final-summary

Cross-Phase Data Flow

Phase 1 → Phase 2:

# Phase 2 reviewers check if Phase 1 passed
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/phase-1/*/results"

# Only proceed if all automated checks passed
if [ "$(jq '.all_passed' < phase1_results.json)" = "true" ]; then
  # Spawn specialist reviewers
  npx claude-flow task orchestrate --strategy parallel
fi

Phase 2 → Phase 3:

# Phase 3 integration analysis references specialist findings
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/phase-2/security-manager/security-review"
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/phase-2/performance-analyzer/performance-review"

# Risk analysis considers all specialist findings

Phase 3 → Phase 4:

# Phase 4 final decision aggregates all prior phases
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/**"

# Generate comprehensive summary

---

Scripts & Automation

Pre-Review Initialization

#!/bin/bash
# Initialize code review workflow

PR_NUMBER="$1"
REPO="$2"  # e.g., "owner/repo"
PR_ID="${REPO}/pulls/${PR_NUMBER}"

# Fetch PR metadata via GitHub API
PR_DATA=$(gh pr view ${PR_NUMBER} --json number,title,author,files,additions,deletions)

# Setup coordination
npx claude-flow hooks pre-task --description "Code review: PR #${PR_NUMBER}"

# Initialize star topology swarm (central coordinator + specialists)
npx claude-flow swarm init --topology star --max-agents 15 --strategy specialized

# Store PR metadata
npx claude-flow memory store --key "code-review/${PR_ID}/metadata" --value "${PR_DATA}"

echo "✅ Code review initialized: PR #${PR_NUMBER}"

Automated Check Gate

#!/bin/bash
# Execute Phase 1 automated checks (gate)

PR_ID="$1"

echo "🤖 Running automated checks..."

# Run checks in parallel
npx claude-flow task orchestrate --strategy parallel --max-agents 4 << EOF
  lint: npm run lint
  test: npm test
  coverage: npm run test:coverage
  build: npm run build
EOF

# Aggregate results
LINT_STATUS=$(npx claude-flow memory retrieve --key "code-review/${PR_ID}/phase-1/code-analyzer/lint-results" | jq -r '.status')
TEST_STATUS=$(npx claude-flow memory retrieve --key "code-review/${PR_ID}/phase-1/tester/test-results" | jq -r '.status')
COVERAGE_OK=$(npx claude-flow memory retrieve --key "code-review/${PR_ID}/phase-1/qa-engineer/coverage-report" | jq -r '.meets_threshold')
BUILD_STATUS=$(npx claude-flow memory retrieve --key "code-review/${PR_ID}/phase-1/code-analyzer/build-status" | jq -r '.status')

# Check if all passed
if [ "$LINT_STATUS" = "PASS" ] && [ "$TEST_STATUS" = "PASS" ] && [ "$COVERAGE_OK" = "true" ] && [ "$BUILD_STATUS" = "PASS" ]; then
  echo "✅ All automated checks passed. Proceeding to specialist reviews."
  exit 0
else
  echo "❌ Automated checks failed. Requesting fixes from author."
  gh pr review  --request-changes --body 
   1

Parallel Specialist Review

#!/bin/bash
# Execute Phase 2 specialist reviews in parallel

PR_ID="$1"

echo "👥 Spawning specialist reviewers..."

# Spawn all reviewers concurrently via Claude Flow
npx claude-flow task orchestrate --strategy parallel --max-agents 10 << EOF
  code_quality: Review code quality (readability, maintainability, best practices)
  security: Review security vulnerabilities (OWASP Top 10, secrets, auth)
  performance: Review performance (algorithms, resource usage, optimizations)
  architecture: Review architecture consistency (patterns, integration, scalability)
  documentation: Review documentation completeness (code docs, API docs, changelog)
  style: Review code style consistency
  dependencies: Review dependency security and updates
  test_coverage: Review test coverage gaps
  external_docs: Review README and migration guides
  integration: Review integration fit with existing codebase
EOF

# Wait for all reviews to complete
npx claude-flow task status --wait

echo "✅ All specialist reviews complete."

Final Decision Script

#!/bin/bash
# Generate final decision and notify author

PR_ID="$1"
PR_NUMBER=$(echo $PR_ID | cut -d'/' -f3)

# Retrieve all review data
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/**" > "/tmp/${PR_ID}-reviews.json"

# Count issues by severity
CRITICAL_COUNT=$(jq '[.. | .severity? | select(. == "CRITICAL")] | length' /tmp/${PR_ID}-reviews.json)
HIGH_COUNT=$(jq '[.. | .severity? | select(. == "HIGH")] | length' /tmp/${PR_ID}-reviews.json)
BLOCKING_COUNT=$((CRITICAL_COUNT + HIGH_COUNT))

# Determine decision
if [ $CRITICAL_COUNT -gt 0 ] || [ $BLOCKING_COUNT -gt 5 ]; then
  DECISION="REJECT"
elif [ $BLOCKING_COUNT -gt 0 ]; then
  DECISION="REQUEST_CHANGES"
else
  DECISION="APPROVE"
fi

echo "📊 Review Decision: ${DECISION}"
echo "   Critical Issues: ${CRITICAL_COUNT}"
echo "   High-Severity Issues: ${HIGH_COUNT}"

# Notify author via GitHub
case $DECISION in
  APPROVE)
    gh pr review ${PR_NUMBER} --approve --body "✅ All quality checks passed. Ready to merge."
    gh  edit  --add-label 
    ;;
  REQUEST_CHANGES)
    gh  review  --request-changes --body-file 
    gh  edit  --add-label 
    ;;
  REJECT)
    gh  review  --request-changes --body-file 
    gh  edit  --add-label 
    ;;



npx claude-flow hooks post-task --task-id  --export-metrics 

---

Success Criteria

Review Quality Metrics

• Coverage: All quality dimensions reviewed (code, security, performance, architecture, docs)
• Consistency: Reviews follow established guidelines and standards
• Actionability: All feedback is specific, constructive, and actionable
• Timeliness: Reviews completed within 4 hours (business hours)

Code Quality Gates

• Automated Tests: 100% passing (no failing tests)
• Code Coverage: > 80% overall, > 90% for new code
• Linting: 0 violations (all style rules followed)
• Security: 0 critical issues, 0 high-severity issues
• Performance: No high-impact performance regressions
• Documentation: 100% of public APIs documented

Process Metrics

• Review Turnaround: < 4 hours (from PR creation to decision)
• Author Satisfaction: > 4/5 (feedback is helpful and constructive)
• Defect Escape Rate: < 1% (issues found in production that should have been caught)
• False Positive Rate: < 5% (flagged issues that weren't actually problems)

---

Usage Examples

Example 1: Small Feature PR (Simple)

# Feature: Add email validation to registration form
PR_NUMBER=245
PR_ID="acme-app/pulls/245"

# Initialize review
./init-review.sh ${PR_NUMBER} "acme/acme-app"

# Phase 1: Automated checks (5 minutes)
./automated-checks.sh ${PR_ID}
# Output: All checks passed

# Phase 2: Specialist reviews (30 minutes - small PR)
./specialist-reviews.sh ${PR_ID}
# Output: 3 minor issues (all LOW severity)

# Phase 3: Integration analysis (10 minutes)
# Output: No integration concerns, backward compatible

# Phase 4: Final decision
./final-decision.sh ${PR_ID}
# Decision: ✅ APPROVE
# Output: "All quality checks passed. 3 minor suggestions for future consideration."

Example 2: Large Refactoring PR (Complex)

# Refactoring: Migrate from REST to GraphQL
PR_NUMBER=312
PR_ID="acme-app/pulls/312"

# Initialize review
./init-review.sh ${PR_NUMBER} "acme/acme-app"

# Phase 1: Automated checks (10 minutes)
./automated-checks.sh ${PR_ID}
# Output: All checks passed, coverage 94%

# Phase 2: Specialist reviews (2 hours)
./specialist-reviews.sh ${PR_ID}
# Output: 15 findings
#   - 1 HIGH/SECURITY (authentication flow changed, needs verification)
#   - 2 HIGH/PERFORMANCE (N+1 queries in new resolvers)
#   - 3 MAJOR/ARCHITECTURE (GraphQL schema design concerns)
#   - 9 MEDIUM/LOW (documentation, minor improvements)

# Phase 3: Integration analysis (1 hour)
# Output: Breaking changes for API clients, migration guide needed
# Risk: HIGH (affects all API consumers)

# Phase 4: Final decision
./final-decision.sh ${PR_ID}
# Decision: ⏸️ REQUEST CHANGES
# Output: "3 blocking issues (security + performance). Add feature flag for gradual rollout. Provide migration guide for API clients."

Example 3: Security Patch PR (Critical)

# Security: Fix SQL injection vulnerability
PR_NUMBER=418
PR_ID="acme-app/pulls/418"

# Initialize expedited review
./init-review.sh ${PR_NUMBER} "acme/acme-app"

# Phase 1: Automated checks (5 minutes)
./automated-checks.sh ${PR_ID}
# Output: All checks passed

# Phase 2: Focus on security review (30 minutes)
npx claude-flow agent spawn --type security-manager --focus "comprehensive-audit"
# Output: Vulnerability fixed correctly, no new issues introduced

# Phase 3: Integration analysis (15 minutes)
# Output: Backward compatible, zero downtime deployment

# Phase 4: Fast-track approval
./final-decision.sh ${PR_ID}
# Decision: ✅ APPROVE (EXPEDITED)
# Output: "Security fix verified. No regressions. Approved for immediate merge and deployment."

# Deploy immediately
gh pr merge ${PR_NUMBER} --admin --squash

---

GraphViz Process Diagram

See when-reviewing-pull-request-orchestrate-comprehensive-code-review-process.dot for visual workflow representation showing:

• 4 phases with star topology coordination
• 15 specialist reviewer interactions
• Automated gate (Phase 1) preventing bad code from entering review
• Parallel specialist reviews (Phase 2) for efficiency
• Integration analysis (Phase 3) for deployment safety
• Final decision logic with author notification

---

Quality Checklist

Before considering code review complete, verify:

• Phase 1: All automated checks passing (lint, tests, coverage, build)
• Phase 2: All specialist reviews completed, findings categorized
• Phase 3: Integration impact analyzed, deployment plan documented
• Phase 4: Final decision made, author notified, GitHub status updated

Memory Verification:

• code-review/${PR_ID}/metadata - PR information
• code-review/${PR_ID}/phase-1/* - Automated check results
• code-review/${PR_ID}/phase-2/* - Specialist review findings
• code-review/${PR_ID}/phase-3/* - Integration analysis
• code-review/${PR_ID}/phase-4/final-summary - Comprehensive report

Feedback Quality:

• All feedback is specific (file, line, issue clearly identified)
• All feedback is actionable (how to fix provided)
• All feedback is constructive (not just criticism, but improvement suggestions)
• Severity is appropriate (not overstating or understating issues)

---

Workflow Complexity: Medium (15 agents, 4 hours, 4 phases) Coordination Pattern: Star topology with parallel specialist reviews Memory Footprint: ~20-30 memory entries per PR review Typical Use Case: Comprehensive PR review requiring validation across multiple quality dimensions