when-reviewing-pull-request-orchestrate-comprehensive-code-review
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.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-21
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: when-reviewing-pull-request-orchestrate-comprehensive-code-review
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**
```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 Concurrently**
Each specialist reviews the PR from their domain expertise:
**Code Quality Review** (Code Analyzer):
```bash
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**:
```json
{
"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"
}
],
"rating": 4,
"overall_assessment": "Good code quality with minor improvements needed"
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-2/code-analyzer/quality-review`
**Security Review** (Security Manager):
```bash
npx claude-flow agent spawn --type security-manager --focus "security-comprehensive"
```
Reviews:
- **Authentication & Authorization**: Proper auth checks, no privilege escalation, secure sessions
- **Data Security**: Input validation (injection prevention), output encoding (XSS prevention), sensitive data encryption, no hardcoded secrets
- **OWASP Top 10**: SQL Injection, XSS, CSRF, insecure dependencies, security misconfigurations
Severity: CRITICAL/HIGH/MEDIUM/LOW
**Findings Format**:
```json
{
"category": "security",
"findings": [
{
"severity": "HIGH",
"file": "src/api/users.ts",
"line": 78,
"issue": "User input not sanitized before database query (SQL Injection risk)",
"owasp_category": "A03:2021 – Injection",
"suggestion": "Use parameterized queries or ORM with proper escaping"
},
{
"severity": "MEDIUM",
"file": "src/config/secrets.ts",
"line": 12,
"issue": "API key appears to be hardcoded (potential secret leak)",
"suggestion": "Move to environment variables and add to .env.example"
}
],
"critical_count": 0,
"high_count": 1,
"medium_count": 1,
"overall_assessment": "1 high-severity issue must be fixed before merge"
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-2/security-manager/security-review`
**Performance Review** (Performance Analyzer):
```bash
npx claude-flow agent spawn --type perf-analyzer --focus "performance-optimization"
```
Reviews:
- **Algorithmic Efficiency**: Time complexity (no unnecessary O(n²)), efficient data structures, no redundant iterations
- **Resource Usage**: No memory leaks, proper cleanup (connections, files, timers), efficient queries (avoid N+1)
- **Optimization Opportunities**: Caching potential, parallelization, database indexes, API call reduction
Impact: HIGH/MEDIUM/LOW
**Findings Format**:
```json
{
"category": "performance",
"findings": [
{
"impact": "HIGH",
"file": "src/services/user-service.ts",
"line": 125,
"issue": "N+1 query problem: Loading user roles in loop (1 + N queries)",
"performance_cost": "10x slower for 100 users",
"suggestion": "Use eager loading with JOIN or batch query with IN clause"
}
],
"high_impact_count": 1,
"estimated_improvement": "10x faster with suggested optimizations",
"overall_assessment": "Significant performance regression without optimization"
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-2/performance-analyzer/performance-review`
**Architecture Review** (System Architect):
```bash
npx claude-flow agent spawn --type system-architect --focus "architecture-consistency"
```
Reviews:
- **Design Patterns**: Follows established patterns, appropriate abstraction, dependency injection, clean architecture
- **Integration**: Fits with existing code, no unexpected side effects, backward compatibility, API contracts respected
- **Scalability**: Supports future growth, no hardcoded limits, stateless design, horizontally scalable
Concerns: BLOCKER/MAJOR/MINOR
**Findings Format**:
```json
{
"category": "architecture",
"findings": [
{
"concern": "MAJOR",
"file": "src/services/payment-service.ts",
"issue": "Payment service directly couples to Stripe SDK (violates adapter pattern)",
"impact": "Difficult to switch payment providers in future",
"suggestion": "Create PaymentProvider interface and StripeAdapter implementation"
}
],
"blocker_count": 0,
"major_count": 1,
"overall_assessment": "Architecture mostly consistent with 1 major design concern"
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-2/system-architect/architecture-review`
**Documentation Review** (API Documentation Specialist):
```bash
npx claude-flow agent spawn --type api-docs --focus "documentation-comprehensive"
```
Reviews:
- **Code Documentation**: Public APIs documented (JSDoc/docstring), complex logic explained, non-obvious behavior noted
- **External Documentation**: README updated, API docs updated, migration guide (if breaking), changelog updated
- **Tests as Documentation**: Descriptive test names, test coverage demonstrates usage, edge cases documented
Completeness: 0-100%
**Findings Format**:
```json
{
"category": "documentation",
"findings": [
{
"severity": "MEDIUM",
"file": "src/api/webhooks.ts",
"issue": "New webhook endpoint /api/webhooks/stripe missing API documentation",
"suggestion": "Add JSDoc with parameters, responses, and usage example"
}
],
"code_doc_coverage": 75,
"external_doc_updated": false,
"overall_assessment": "75% complete, missing API docs and changelog update"
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-2/api-documentation-specialist/docs-review`
**Additional Specialist Reviews** (run in parallel):
- **Style Audit** (Style Auditor): Code style consistency, formatting compliance
- **Dependency Audit** (Dependency Analyzer): Outdated packages, security vulnerabilities in deps
- **Test Coverage** (Test Coverage Reviewer): Coverage gaps, missing edge cases
- **Documentation Completeness** (Documentation Reviewer): README, changelog, migration guides
Each follows similar format with findings, severity, and recommendations.
3. **Aggregate Specialist Reviews**
```bash
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/phase-2/*/review"
npx claude-flow agent spawn --type pr-manager --focus "aggregation"
```
**PR Manager** synthesizes all reviews:
- Total findings: 15 issues (0 critical, 1 high, 8 medium, 6 low)
- Quality rating: 4/5 stars
- Security: 1 high-severity issue
- Performance: 1 high-impact issue
- Architecture: 1 major concern
- Documentation: 75% complete
Categorize issues:
- **Blocking Issues** (must fix before merge): High-severity security issue, high-impact performance regression
- **High-Priority** (should fix): Major architecture concern, medium security issues
- **Nice-to-Have** (can fix later): Low-severity code quality improvements
**Memory Storage**:
```bash
npx claude-flow memory store --key "code-review/${PR_ID}/phase-2/aggregated-review" \
--value "${AGGREGATED_FINDINGS_JSON}"
```
**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**
```bash
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:
```bash
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**
```bash
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**:
```json
{
"infrastructure_changes": ["Add Redis cache for session storage"],
"database_migrations": ["Add index on users.email for faster lookups"],
"config_updates": ["Add REDIS_URL environment variable"],
"backward_compatible": true,
"rollback_complexity": "LOW",
"deployment_risk": "MEDIUM"
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-3/devops-engineer/deployment-impact`
3. **User Impact Assessment**
```bash
npx claude-flow agent spawn --type planner --focus "user-impact"
```
**Product Manager** assesses:
- Does this improve user experience?
- Any user-facing changes? (UI/UX)
- Consistent with design system?
- Analytics/tracking updated?
- Feature flags needed?
**Findings**:
```json
{
"user_facing_changes": ["New export functionality in dashboard"],
"ux_impact": "POSITIVE",
"design_system_compliant": true,
"analytics_updated": false,
"feature_flag_recommended": true
}
```
**Memory Pattern**: `code-review/${PR_ID}/phase-3/product-manager/user-impact`
4. **Risk Assessment**
```bash
npx claude-flow memory retrieve --pattern "code-review/${PR_ID}/phase-3/*"
npx claude-flow agent spawn --type reviewer --focus "risk-analysis"
```
**Code Reviewer** analyzes:
- What's the blast radius of this change? (how many users/services affected)
- Worst-case failure scenario? (data loss, downtime, security breach)
- Do we have rollback procedures? (tested and documented)
- Should this be feature-f