Arguments

[PR number, GitHub URL, branch name, or latest]

Review Command

<command_purpose> Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and Git worktrees for deep local inspection. </command_purpose>

Introduction

Senior Code Review Architect with expertise in security, performance, architecture, and quality assurance

Prerequisites

Main Tasks

1. Determine Review Target & Setup (ALWAYS FIRST)

<review_target> #$ARGUMENTS </review_target>

Immediate Actions:

<task_list>

• Determine review type: PR number (numeric), GitHub URL, file path (.md), or empty (current branch)
• Check current git branch
• If ALREADY on the target branch (PR branch, requested branch name, or the branch already checked out for review) → proceed with analysis on current branch
• If DIFFERENT branch than the review target → offer to use worktree: "Use git-worktree skill for isolated Call /git-worktree skill with branch name
• Fetch PR metadata using gh pr view --json for title, body, files, linked issues
• Set up language-specific analysis tools
• Prepare security scanning environment
• Make sure we are on the branch we are reviewing. Use gh pr checkout to switch to the branch or manually checkout the branch.

Ensure that the code is ready for analysis (either in worktree or on current branch). ONLY then proceed to the next step.

</task_list>

Protected Artifacts

<protected_artifacts> The following paths are compound-engineering pipeline artifacts and must never be flagged for deletion, removal, or gitignore by any review agent:

• docs/plans/*.md — Plan files created by /workflows-plan. These are living documents that track implementation progress (checkboxes are checked off by /workflows-work).
• docs/solutions/*.md — Solution documents created during the pipeline.

If a review agent flags any file in these directories for cleanup or removal, discard that finding during synthesis. Do not create a task for it. </protected_artifacts>

Parallel subagents to review the PR:

<parallel_tasks>

Run ALL or most of these as subagents in parallel:

1. git-history-analyzer(PR content)
2. analyze-dependencies(PR content)
3. analyze-patterns(PR content)
4. analyze-architecture(PR content)
5. review-security(PR content)
6. analyze-performance(PR content)
7. review-data-integrity(PR content)
8. review-agent-native(PR content) - Verify new features are agent-accessible

</parallel_tasks>

Conditional skills (Run if applicable):

<conditional_skills>

These skills are run ONLY when the PR matches specific criteria. Check the PR files list to determine if they apply:

If PR contains database migrations or data backfills:

14. review-data-migrations(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
15. verify-deployment(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries

When to run migration skills:

• PR includes files matching db/migrate/*.rb
• PR modifies columns that store IDs, enums, or mappings
• PR includes data backfill scripts or rake tasks
• PR changes how data is read/written (e.g., changing from FK to string column)
• PR title/body mentions: migration, backfill, data transformation, ID mapping

What these skills check:

• review-data-migrations: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns
• verify-deployment: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans

</conditional_skills>

4. Ultra-Thinking Deep Dive Phases

For each phase below, spend maximum cognitive effort. Think step by step. Consider all angles. Question assumptions. And bring all reviews in a synthesis to the user.

Phase 3: Stakeholder Perspective Analysis

<thinking_prompt>Put yourself in each stakeholder's shoes. What matters to them? What are their pain points? </thinking_prompt>

<stakeholder_perspectives>

1. Developer Perspective

   • How easy is this to understand and modify?
   • Are the APIs intuitive?
   • Is debugging straightforward?
   • Can I test this easily?

2. Operations Perspective

   • How do I deploy this safely?
   • What metrics and logs are available?
   • How do I troubleshoot issues?
   • What are the resource requirements?

3. End User Perspective

   • Is the feature intuitive?
   • Are error messages helpful?
   • Is performance acceptable?
   • Does it solve my problem?

4. Security Team Perspective

   • What's the attack surface?
   • Are there compliance requirements?
   • How is data protected?
   • What are the audit capabilities?

5. Business Perspective

   • What's the ROI?
   • Are there legal/compliance risks?
   • How does this affect time-to-market?
   • What's the total cost of ownership? </stakeholder_perspectives>

Phase 4: Scenario Exploration

<thinking_prompt> Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress? </thinking_prompt>

<scenario_checklist>

• Happy Path: Normal operation with valid inputs
• Invalid Inputs: Null, empty, malformed data
• Boundary Conditions: Min/max values, empty collections
• Concurrent Access: Race conditions, deadlocks
• Scale Testing: 10x, 100x, 1000x normal load
• Network Issues: Timeouts, partial failures
• Resource Exhaustion: Memory, disk, connections
• Security Attacks: Injection, overflow, DoS
• Data Corruption: Partial writes, inconsistency
• Cascading Failures: Downstream service issues

</scenario_checklist>

6. Multi-Angle Review Perspectives

Technical Excellence Angle

• Code craftsmanship evaluation
• Engineering best practices
• Technical documentation quality
• Tooling and automation assessment

Business Value Angle

• Feature completeness validation
• Performance impact on users
• Cost-benefit analysis
• Time-to-market considerations

Risk Management Angle

• Security risk assessment
• Operational risk evaluation
• Compliance risk verification
• Technical debt accumulation

Team Dynamics Angle

• Code review etiquette
• Knowledge sharing effectiveness
• Collaboration patterns
• Mentoring opportunities

4. Simplification and Minimalism Review

Run the Task review-code-simplicity() to see if we can simplify the code.

5. Findings Synthesis and Task Creation Using tasks-router Skill

<critical_requirement> ALL findings MUST be stored using the tasks-router skill. It selects tasks-file (tasks/ directory) or tasks-beads (.beads/) based on the repo. Create tasks immediately after synthesis - do NOT present findings for user approval first. </critical_requirement>

Step 1: Synthesize All Findings

<synthesis_tasks>

• Collect findings from all parallel agents
• Discard any findings that recommend deleting or gitignoring files in docs/plans/ or docs/solutions/ (see Protected Artifacts above)
• Categorize by type: security, performance, architecture, quality, etc.
• Assign severity levels: 🔴 CRITICAL (P1), 🟡 IMPORTANT (P2), 🔵 NICE-TO-HAVE (P3)
• Remove duplicate or overlapping findings
• Estimate effort for each finding (Small/Medium/Large)

</synthesis_tasks>

Step 2: Create Tasks Using tasks-router

<critical_instruction> Use the tasks-router skill to create tasks for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all tasks in parallel using the skill, then summarize results to user. </critical_instruction>

Implementation Options:

Option A: Direct Creation (Fast)

• Create tasks directly using the selected system
• All findings in parallel for speed
• If tasks-file: use standard template from ../tasks-file/assets/task-template.md
• If tasks-file: follow naming convention {issue_id}-pending-{priority}-{description}.md
• If tasks-beads: use br create --json + br update --design/--notes/--acceptance-criteria --json

Option B: Subagents in Parallel (Recommended for Scale) For large PRs with 15+ findings, use subagents to create finding files in parallel:

# Launch multiple tasks-router in parallel
- Create tasks for first finding
- Create tasks for second finding
- Create tasks for third finding
etc. for each finding.

Subagents can:

• Process multiple findings simultaneously
• Write detailed task files with all sections filled
• Organize findings by severity
• Create comprehensive Proposed Solutions
• Add acceptance criteria and work logs
• Complete much faster than sequential processing

Execution Strategy:

1. Synthesize all findings into categories (P1/P2/P3)
2. Group findings by severity
3. Launch 3 parallel subagents (one per severity level)
4. Each subagent creates its batch of tasks using the tasks-router skill
5. Consolidate results and present summary

Process (Using tasks-router Skill):

1. For each finding:

   • Determine severity (P1/P2/P3)
   • Write detailed Problem Statement and Findings
   • Create 2-3 Proposed Solutions with pros/cons/effort/risk
   • Estimate effort (Small/Medium/Large)
   • Add acceptance criteria and work log

2. Use tasks-router skill for structured task management:

   bashCopy

   skill: tasks-router
   

   The skill provides:

   • If tasks-file: template location ../tasks-file/assets/task-template.md
   • If tasks-file: naming convention {issue_id}-{status}-{priority}-{description}.md
   • If tasks-file: YAML frontmatter structure, required sections
   • If tasks-beads: use br create --json, br update --design --json (solutions/technical details), br update --notes --json (findings/resources), br update --acceptance-criteria --json, and comments for work log

3. Create task files in parallel:

   bashCopy

   {next_id}-pending-{priority}-{description}.md
   

4. Examples:

   Copy

   001-pending-p1-path-traversal-vulnerability.md
   002-pending-p1-api-response-validation.md
   003-pending-p2-concurrency-limit.md
   004-pending-p3-unused-parameter.md
   

5. If tasks-file, follow template structure from ../tasks-file/assets/task-template.md. If tasks-beads, map sections to Beads fields.

Task File Structure (from template):

Each task must include:

• YAML frontmatter: status, priority, issue_id, tags, dependencies
• Problem Statement: What's broken/missing, why it matters
• Findings: Discoveries from agents with evidence/location
• Proposed Solutions: 2-3 options, each with pros/cons/effort/risk
• Recommended Action: (Filled during triage, leave blank initially)
• Technical Details: Affected files, components, database changes
• Acceptance Criteria: Testable checklist items
• Work Log: Dated record with actions and learnings
• Resources: Links to PR, issues, documentation, similar patterns

If tasks-beads is selected, map these sections to Beads fields (see tasks-beads skill).

File naming convention:

{issue_id}-{status}-{priority}-{description}.md

Examples:
- 001-pending-p1-security-vulnerability.md
- 002-pending-p2-performance-optimization.md
- 003-pending-p3-code-cleanup.md

Status values:

• pending - New findings, needs triage/decision
• ready - Approved by manager, ready to work
• complete - Work finished

Priority values:

• p1 - Critical (blocks merge, security/data issues)
• p2 - Important (should fix, architectural/performance)
• p3 - Nice-to-have (enhancements, cleanup)

Tagging: Always add code-review tag, plus: security, performance, architecture, rails, quality, etc.

Step 3: Summary Report

After creating all task files, present comprehensive summary:

## ✅ Code Review Complete

**Review Target:** PR #XXXX - [PR Title] **Branch:** [branch-name]

### Findings Summary:

- **Total Findings:** [X]
- **🔴 CRITICAL (P1):** [count] - BLOCKS MERGE
- **🟡 IMPORTANT (P2):** [count] - Should Fix
- **🔵 NICE-TO-HAVE (P3):** [count] - Enhancements

### Created Tasks:

**P1 - Critical (BLOCKS MERGE):**

- `001-pending-p1-{finding}.md` - {description} (tasks-file)
- `Issue #123` - {description} (tasks-beads)

**P2 - Important:**

- `003-pending-p2-{finding}.md` - {description} (tasks-file)
- `Issue #124` - {description} (tasks-beads)

**P3 - Nice-to-Have:**

- `005-pending-p3-{finding}.md` - {description} (tasks-file)
- `Issue #125` - {description} (tasks-beads)

### Review Agents Used:

- review-security
- analyze-performance
- analyze-architecture
- review-agent-native
- review-code-simplicity
- [other agents]

### Next Steps:

1. **Address P1 Findings**: CRITICAL - must be fixed before merge

   - Review each P1 task in detail
   - Implement fixes or request exemption
   - Verify fixes before merging PR

2. **Triage All Tasks**:
   ```bash
   /triage  # Uses tasks-router and routes to tasks-file or tasks-beads
   ```

3. Work on Approved Tasks:

   bashCopy

   /resolve_task_parallel  # Fix all approved items efficiently
   

4. Track Progress:

   • If tasks-file: rename file when status changes: pending → ready → complete
   • If tasks-beads: update status with br update --json and add work log comments
   • Commit tasks: git add tasks/ (tasks-file) or br sync --flush-only --json && git add .beads/ (tasks-beads)

Severity Breakdown:

🔴 P1 (Critical - Blocks Merge):

• Security vulnerabilities
• Data corruption risks
• Breaking changes
• Critical architectural issues

🟡 P2 (Important - Should Fix):

• Performance issues
• Significant architectural concerns
• Major code quality problems
• Reliability issues

🔵 P3 (Nice-to-Have):

• Minor improvements
• Code cleanup
• Optimization opportunities
• Documentation updates

### 7. End-to-End Testing (Optional)

<detect_project_type>

**First, detect the project type from PR files:**

| Indicator | Project Type |
|-----------|--------------|
| `*.xcodeproj`, `*.xcworkspace`, `Package.swift` (iOS) | iOS/macOS |
| `Gemfile`, `package.json`, `app/views/*`, `*.html.*` | Web |
| Both iOS files AND web files | Hybrid (test both) |

</detect_project_type>

<offer_testing>

After presenting the Summary Report, offer appropriate testing based on project type:

**For Web Projects:**
```markdown
**"Want to run browser tests on the affected pages?"**
1. Yes - run `/test-browser`
2. No - skip

For iOS Projects:

**"Want to run Xcode simulator tests on the app?"**
1. Yes - run `/test-xcode`
2. No - skip

For Hybrid Projects:

**"Want to run end-to-end tests?"**
1. Web only - run `/test-browser`
2. iOS only - run `/test-xcode`
3. Both - run both commands
4. No - skip

</offer_testing>

If User Accepts Web Testing:

Spawn a subagent to run browser tests (preserves main context):

Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating tasks and fixing.")

The subagent will:

1. Identify pages affected by the PR
2. Navigate to each page and capture snapshots (using agent-browser CLI)
3. Check for console errors
4. Test critical interactions
5. Pause for human verification on OAuth/email/payment flows
6. Create P1 tasks for any failures
7. Fix and retry until all tests pass

Standalone: /test-browser [PR number]

If User Accepts iOS Testing:

Spawn a subagent to run Xcode tests (preserves main context):

Task general-purpose("Run /test-xcode for scheme [name]. Build for simulator, install, launch, take screenshots, check for crashes.")

The subagent will:

1. Verify XcodeBuildMCP is installed
2. Discover project and schemes
3. Build for iOS Simulator
4. Install and launch app
5. Take screenshots of key screens
6. Capture console logs for errors
7. Pause for human verification (Sign in with Apple, push, IAP)
8. Create P1 tasks for any failures
9. Fix and retry until all tests pass

Standalone: /test-xcode [scheme]

Important: P1 Findings Block Merge

Any 🔴 P1 (CRITICAL) findings must be addressed before merging the PR. Present these prominently and ensure they're resolved before accepting the PR.