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

What this skill does

# 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**
   ```bash
   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**:
   ```bash
   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**
   ```bash
   npx claude-flow task orchestrate --strategy parallel --max-agents 4
   ```

   Spawn all automated check agents concurrently:

   **Linting Check** (Code Analyzer):
   ```bash
   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**: `code-review/${PR_ID}/phase-1/code-analyzer/lint-results`

   **Test Execution** (Tester):
   ```bash
   npx claude-flow agent spawn --type tester --focus "test-execution"

   # Run test suite
   npm test  # Jest/Mocha
   # or
   pytest  # Python
   # or
   rspec  # Ruby
   ```

   Validates:
   - All unit tests passing
   - All integration tests passing
   - All E2E tests passing (if applicable)
   - No flaky test failures
   - Test execution time within limits

   **Memory Pattern**: `code-review/${PR_ID}/phase-1/tester/test-results`

   **Coverage Analysis** (QA Engineer):
   ```bash
   npx claude-flow agent spawn --type tester --focus "coverage"

   # Generate coverage report
   npm run test:coverage
   ```

   Checks:
   - Overall coverage > 80%
   - New code coverage > 90%
   - No critical paths uncovered
   - Coverage delta (did coverage decrease?)
   - Untested branches and conditions

   **Memory Pattern**: `code-review/${PR_ID}/phase-1/qa-engineer/coverage-report`

   **Build Validation** (Code Analyzer):
   ```bash
   # Clean build validation
   npm run build
   # or
   python setup.py build
   ```

   Validates:
   - Clean build (no errors, no warnings)
   - Type checking passes (TypeScript, mypy)
   - No broken dependencies
   - Bundle size within limits (for frontend)
   - No circular dependencies

   **Memory Pattern**: `code-review/${PR_ID}/phase-1/code-analyzer/build-status`

3. **Evaluate Gate 1 Results**
   ```bash
   npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/phase-1/*/results"
   ```

   **PR Manager** aggregates automated results:
   - Lint: PASS/FAIL (violations count)
   - Tests: PASS/FAIL (passed/failed/skipped)
   - Coverage: PASS/FAIL (percentage, delta)
   - Build: PASS/FAIL (errors/warnings)

   **Decision Logic**:
   ```javascript
   if (lintFailed || testsFailed || buildFailed) {
     // Request fixes from author
     await notifyAuthor({
       status: 'CHANGES_REQUESTED',
       message: 'Automated checks failed. Please fix before review continues.',
       details: summarizeFailures()
     });

     // Store feedback and stop review
     await memory_store(`code-review/${PR_ID}/phase-1/automated-feedback`);
     return; // Stop review until fixed
   }

   // All automated checks passed, proceed to Phase 2
   await notifyAuthor({
     status: 'IN_REVIEW',
     message: 'Automated checks passed. Proceeding with specialized reviews.'
   });
   ```

**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**
   ```bash
   npx claude-flow task orchestrate --strategy parallel --max-agents 10 --priority high
   ```

2. **Spawn All Specialist Reviewers Concurren