// 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.
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.
allowed-tools
Read, Task, TodoWrite, Glob, Grep
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.
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.
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"}],"rating":4,"overall_assessment":"Good code quality with minor improvements needed"}
{"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"}
Optimization Opportunities: Caching potential, parallelization, database indexes, API call reduction
Impact: HIGH/MEDIUM/LOW
Findings Format:
{"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"}
{"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"}
Tests as Documentation: Descriptive test names, test coverage demonstrates usage, edge cases documented
Completeness: 0-100%
Findings Format:
{"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"}
{"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"}
{"user_facing_changes":["New export functionality in dashboard"],"ux_impact":"POSITIVE","design_system_compliant":true,"analytics_updated":false,"feature_flag_recommended":true}
Do we have rollback procedures? (tested and documented)
Should this be feature-flagged? (gradual rollout)
Is monitoring and alerting adequate? (can detect issues quickly)
Risk Matrix:
{"blast_radius":"MEDIUM (affects 30% of users)","worst_case_scenario":"Temporary export failures (no data loss)","rollback_available":true,"rollback_tested":false,"feature_flag_needed":true,"monitoring_adequate":true,"overall_risk":"MEDIUM","recommendation":"CONDITIONAL_APPROVE (add feature flag + test rollback)"}
## 🔍 Comprehensive Code Review Complete
Thank you for your contribution! Our automated review system has completed a thorough analysis.
### ✅ What Went Well- All automated checks passing (tests, coverage, linting)
- Clean code architecture overall
- Good test coverage (93.5%)
### ⚠️ Issues Requiring Attention#### Blocking Issues (Must Fix Before Merge)1.**[HIGH/SECURITY]** SQL Injection Risk
-**File**: `src/api/users.ts:78` -**Issue**: User input not sanitized before database query
-**Fix**: Use parameterized queries or ORM with proper escaping
-**Priority**: CRITICAL
2.**[HIGH/PERFORMANCE]** N+1 Query Problem
-**File**: `src/services/user-service.ts:125` -**Issue**: Loading user roles in loop (10x slower for 100 users)
-**Fix**: Use eager loading with JOIN or batch query
-**Priority**: HIGH
#### Recommendations (Should Address)3.**[MAJOR/ARCHITECTURE]** Payment Service Coupling
- Create PaymentProvider interface for future flexibility
- See: [Architecture Best Practices](link)
4.**[MEDIUM/DOCUMENTATION]** Missing API Documentation
- Add JSDoc for webhook endpoint
- Update changelog with this new feature
### 🔄 Next Steps1. Address the 2 blocking issues above
2. Push updates to this PR branch
3. Automated checks will re-run automatically
4. We'll re-review security and performance aspects
5. Once green, we'll approve for merge!
**Estimated time to fix**: 2-4 hours
---
🤖 Generated by Claude Code Review System | [View Full Report](link)
TodoWrite Called: Did you call TodoWrite with 5+ todos?
Example: TodoWrite({ todos: [8-10 items covering all work] })
Work Delegation: Did you delegate to agents (not do work yourself)?
CORRECT: Agents do the implementation via Task()
WRONG: You write the code directly after reading skill
Correct Pattern After Skill Invocation
// After Skill("<skill-name>") is invoked:
[SingleMessage - ALLin parallel]:
Task("Agent 1", "Description of task 1...", "agent-type-1")
Task("Agent 2", "Description of task 2...", "agent-type-2")
Task("Agent 3", "Description of task 3...", "agent-type-3")
TodoWrite({ todos: [
{content: "Task 1 description", status: "in_progress", activeForm: "Working on task 1"},
{content: "Task 2 description", status: "pending", activeForm: "Working on task 2"},
{content: "Task 3 description", status: "pending", activeForm: "Working on task 3"},
]})
Wrong Pattern (DO NOT DO THIS)
// WRONG - Reading skill and then doing work yourself:Skill("<skill-name>")
// Then you write all the code yourself without Task() calls// This defeats the purpose of the skill system!
The skill is NOT complete until all checklist items are checked.
Remember the pattern: Skill() -> Task() -> TodoWrite() - ALWAYS
Core Principles
1. Automated Gates Before Human Review
Principle: Fast-failing automated checks (linting, tests, coverage, build) must pass before expensive specialist reviews begin. No human should review code that fails basic quality gates.
In practice:
Phase 1 runs automated checks in parallel completing within 30 minutes
Linting violations, test failures, or build errors trigger immediate author notification
Phase 2 specialist reviews only begin after all Phase 1 checks pass green
Automated gate prevents wasted reviewer time analyzing code with obvious defects
Author fixes issues and re-submits triggering fresh Phase 1 run before review resumes
2. Parallel Specialist Reviews for Comprehensive Coverage
Principle: Code quality requires evaluation across multiple dimensions (security, performance, architecture, documentation) by domain experts reviewing concurrently.
In practice:
Star topology spawns 10 specialist reviewers in parallel during Phase 2
Each specialist focuses deeply on their domain without distraction from other concerns
Security reviewer analyzes OWASP Top 10 vulnerabilities and auth/auth correctness
Performance reviewer identifies algorithmic inefficiencies and resource leaks
Architecture reviewer validates design patterns and integration consistency
Findings from all specialists aggregate into comprehensive assessment
3. Risk-Based Decision Making with Evidence
Principle: Merge decisions must be deterministic based on severity-weighted findings, not subjective gut feel. Evidence drives recommendations.
In practice:
Critical severity issues automatically block merge requiring fixes before approval
High severity issues (security, performance regressions) request changes with specific remediation
Medium severity issues conditionally approve with recommendations to address
Low severity issues approve with suggestions for future improvement
Decision logic codified in deterministic algorithm ensuring consistency across PRs
Anti-Patterns
Anti-Pattern
Problem
Solution
Skipping Automated Checks
Proceeding directly to human review without automated validation wastes specialist time reviewing code with linting violations, failing tests, or broken builds.
Implement mandatory Phase 1 automated gate. No specialist reviews begin until all automated checks pass. Author must fix issues before review proceeds. Enforce with CI/CD pipeline checks.
Single Reviewer Bottleneck
One generalist reviewer attempts to evaluate all quality dimensions (code, security, performance, architecture) resulting in shallow review missing domain-specific issues.
Deploy star topology with 10 specialist reviewers operating in parallel. Each reviewer focuses deeply on their domain expertise. Aggregate findings into comprehensive assessment covering all dimensions.
Merge Without Risk Assessment
Approving PRs based solely on code quality without analyzing deployment impact, integration risk, or rollback complexity leads to production incidents.
Proceeding directly to human review without automated validation wastes specialist time reviewing code with linting violations, failing tests, or broken builds.
Implement mandatory Phase 1 automated gate. No specialist reviews begin until all automated checks pass. Author must fix issues before review proceeds. Enforce with CI/CD pipeline checks.
Single Reviewer Bottleneck
One generalist reviewer attempts to evaluate all quality dimensions (code, security, performance, architecture) resulting in shallow review missing domain-specific issues.
Deploy star topology with 10 specialist reviewers operating in parallel. Each reviewer focuses deeply on their domain expertise. Aggregate findings into comprehensive assessment covering all dimensions.
Merge Without Risk Assessment
Approving PRs based solely on code quality without analyzing deployment impact, integration risk, or rollback complexity leads to production incidents.
Comprehensive code review orchestration transforms manual, inconsistent review processes into systematic workflows that evaluate PRs across security, performance, architecture, documentation, and integration dimensions within 4 hours. The star topology coordination pattern enables 10+ specialists to review concurrently while maintaining coherence through centralized PR manager aggregation. Automated gates prevent wasted human effort by fast-failing obvious defects before expensive specialist reviews begin.
The workflow's effectiveness stems from balancing speed with thoroughness - Phase 1 automated checks complete in 30 minutes providing immediate feedback, while Phase 2 parallel specialist reviews achieve comprehensive coverage without sequential bottlenecks. The deterministic decision logic in Phase 4 eliminates subjective merge decisions, basing recommendations on severity-weighted findings rather than gut feel. This consistency builds team confidence that review quality remains high regardless of which specialists are available.
Memory coordination enables specialists to reference findings from other reviewers, preventing duplicate work and creating holistic assessments. The security reviewer can reference performance issues when evaluating authentication flows, while the architecture reviewer considers deployment complexity identified by DevOps analysis. This cross-referencing elevates individual specialist insights into collective intelligence greater than sum of parts. Teams implementing this workflow should resist the temptation to skip phases or compress timelines during crunch periods - the 4-hour duration reflects realistic minimum time for thorough multi-dimensional analysis. Rushing reviews surfaces as production incidents that cost far more than modest PR review delays.
