Skip to content

/vt-d-wf-review

Perform exhaustive code reviews using multi-agent analysis, ultra-thinking, and worktrees

Plugin: vt-product-dev
Usage: /vt-d-wf-review [PR number, GitHub URL, branch name, or latest]

Review Command

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

Introduction

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

Prerequisites

- Git repository with GitHub CLI (gh) installed and authenticated - Clean main/master branch - Proper permissions to create worktrees and access the repository - For document reviews: Path to a markdown file or document

Main Tasks

1. Determine Review Target & Setup (ALWAYS FIRST)

#$ARGUMENTS

First, I need to determine the review target type and set up the code for analysis.

Immediate Actions:

  • [ ] 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 skill: git-worktree 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.

Parallel Agents to review the PR:

Run ALL or most of these agents at the same time.

IMPORTANT: Conditional dispatch — Before invoking each agent, check if its definition file exists in the agents directory. If the agent file does not exist, skip it with a note in the review output: "Skipped [agent-name]: agent definition not found." This prevents errors from missing agents and is forward-compatible (new agents are picked up automatically when added).

Always available (core review agents):

  1. Task angular-reviewer(PR content) — if angular.json exists
  2. Task nestjs-reviewer(PR content) — if nest-cli.json exists
  3. Task pattern-recognition-specialist(PR content)
  4. Task architecture-strategist(PR content)
  5. Task security-sentinel(PR content)
  6. Task performance-oracle(PR content)
  7. Task data-integrity-guardian(PR content)
  8. Task agent-native-reviewer(PR content) - Verify new features are agent-accessible

Conditional — invoke only if agent file exists:

  1. Task code-philosopher(PR content) — if agents/review/code-philosopher.md exists
  2. Task devops-harmony-analyst(PR content) — if agents/review/devops-harmony-analyst.md exists
  3. Task dependency-detective(PR content) — if agents/review/dependency-detective.md exists
  4. Task git-history-analyzer(PR content) — if agents/review/git-history-analyzer.md exists
  5. If turbo is used: Task rails-turbo-expert(PR content) — if agents/review/rails-turbo-expert.md exists

Conditional Agents (Run if applicable):

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

If PR contains database migrations (db/migrate/*.rb files) or data backfills:

  1. Task data-migration-expert(PR content) — if agents/review/data-migration-expert.md exists; validates ID mappings match production, checks for swapped values, verifies rollback safety
  2. Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries

When to run migration agents: - 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 agents check: - data-migration-expert: Verifies hard-coded mappings match production reality (prevents swapped IDs), checks for orphaned associations, validates dual-write patterns - deployment-verification-agent: Produces executable pre/post-deploy checklists with SQL queries, rollback procedures, and monitoring plans

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.

Complete system context map with component interactions

Phase 3: Stakeholder Perspective Analysis

ULTRA-THINK: Put yourself in each stakeholder's shoes. What matters to them? What are their pain points?

  1. Developer Perspective

  2. How easy is this to understand and modify?

  3. Are the APIs intuitive?
  4. Is debugging straightforward?

  5. Can I test this easily?

  6. Operations Perspective

  7. How do I deploy this safely?

  8. What metrics and logs are available?
  9. How do I troubleshoot issues?

  10. What are the resource requirements?

  11. End User Perspective

  12. Is the feature intuitive?

  13. Are error messages helpful?
  14. Is performance acceptable?

  15. Does it solve my problem?

  16. Security Team Perspective

  17. What's the attack surface?

  18. Are there compliance requirements?
  19. How is data protected?

  20. What are the audit capabilities?

  21. Business Perspective

  22. What's the ROI?
  23. Are there legal/compliance risks?
  24. How does this affect time-to-market?
  25. What's the total cost of ownership?

Phase 4: Scenario Exploration

ULTRA-THINK: Explore edge cases and failure scenarios. What could go wrong? How does the system behave under stress?

  • [ ] 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

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 code-simplicity-reviewer() to see if we can simplify the code.

5. Findings Synthesis and Todo Creation Using file-todos Skill

ALL findings MUST be stored in the todos/ directory using the file-todos skill. Create todo files immediately after synthesis - do NOT present findings for user approval first. Use the skill for structured todo management.

Step 1: Synthesize All Findings

Consolidate all agent reports into a categorized list of findings. Remove duplicates, prioritize by severity and impact.

  • [ ] Collect findings from all parallel agents
  • [ ] 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)

Step 2: Create Todo Files Using file-todos Skill

Use the file-todos skill to create todo files for ALL findings immediately. Do NOT present findings one-by-one asking for user approval. Create all todo files in parallel using the skill, then summarize results to user.

Implementation Options:

Option A: Direct File Creation (Fast)

  • Create todo files directly using Write tool
  • All findings in parallel for speed
  • Use standard template from plugins/vt-base/assets/todo-template.md
  • Follow naming convention: {issue_id}-pending-{priority}-{description}.md

Option B: Sub-Agents in Parallel (Recommended for Scale) For large PRs with 15+ findings, use sub-agents to create finding files in parallel:

# Launch multiple finding-creator agents in parallel
Task() - Create todos for first finding
Task() - Create todos for second finding
Task() - Create todos for third finding
etc. for each finding.

Sub-agents can:

  • Process multiple findings simultaneously
  • Write detailed todo 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 sub-agents (one per severity level)
  4. Each sub-agent creates its batch of todos using the file-todos skill
  5. Consolidate results and present summary

Process (Using file-todos Skill):

  1. For each finding:

  2. Determine severity (P1/P2/P3)

  3. Write detailed Problem Statement and Findings
  4. Create 2-3 Proposed Solutions with pros/cons/effort/risk
  5. Estimate effort (Small/Medium/Large)

  6. Add acceptance criteria and work log

  7. Use file-todos skill for structured todo management:

skill: file-todos

The skill provides:

  • Template location: plugins/vt-base/assets/todo-template.md
  • Naming convention: {issue_id}-{status}-{priority}-{description}.md
  • YAML frontmatter structure: status, priority, issue_id, tags, dependencies

  • All required sections: Problem Statement, Findings, Solutions, etc.

  • Create todo files in parallel:

{next_id}-pending-{priority}-{description}.md
  1. Examples:
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
  1. Follow template structure: plugins/vt-base/assets/todo-template.md

Todo File Structure (from template):

Each todo 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

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 todo 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 Todo Files:

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

- `001-pending-p1-{finding}.md` - {description}
- `002-pending-p1-{finding}.md` - {description}

**P2 - Important:**

- `003-pending-p2-{finding}.md` - {description}
- `004-pending-p2-{finding}.md` - {description}

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

- `005-pending-p3-{finding}.md` - {description}

### Review Agents Used:

- angular-reviewer (if angular.json exists)
- nestjs-reviewer (if nest-cli.json exists)
- security-sentinel
- performance-oracle
- architecture-strategist
- agent-native-reviewer
- [other agents]

### Next Steps:

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

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

2. **Triage All Todos**:
   ```bash
   ls todos/*-pending-*.md  # View all pending todos
   /vt-d-triage                  # Use slash command for interactive triage
   ```
  1. Work on Approved Todos:
/vt-d-resolve-todo-parallel  # Fix all approved items efficiently
  1. Track Progress:
  2. Rename file when status changes: pending → ready → complete
  3. Update Work Log as you work
  4. Commit todos: git add todos/ && git commit -m "refactor: add code review findings"

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 (Required for Web Projects)

<detect_project_type>

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

| Indicator | Project Type |
|-----------|--------------|
| `*.xcodeproj`, `*.xcworkspace`, `Package.swift` (iOS) | iOS/macOS |
| `package.json` (react/vue/svelte/angular/next/nuxt/remix), `app/views/*`, `*.html.*`, `playwright.config.*`, `vite.config.*` | Web |
| Both iOS files AND web files | Hybrid (test both) |
| None of the above (pure API, CLI, library) | Non-web (skip browser tests) |

</detect_project_type>

<offer_testing>

After presenting the Summary Report, **automatically determine testing requirements** based on project type:

**For Web Projects (browser testing REQUIRED — no user choice):**
```markdown
**Web project detected — running browser tests automatically.**

Browser testing is mandatory for all web UI changes. Dispatching Playwright tests now...

Automatically dispatch browser testing without asking. Do NOT offer "skip" for web projects.

For Non-Web Projects (backend API, CLI, library): 

**No browser testing needed** (non-web project detected).

This appears to be a backend/CLI/library project with no web UI.

For iOS Projects: 

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

For Hybrid Projects (e.g., Rails + Hotwire Native): 

**Web browser tests will run automatically** (web project detected).

**Additionally, want to run iOS simulator tests?**
1. Yes - also run `/xcode-test`
2. No - web tests only

IMPORTANT: Browser testing via Playwright is optional ONLY for: - Backend API changes with no UI modifications - CLI tools and libraries - Infrastructure/deployment changes

For ALL changes touching web UI, browser testing runs automatically and must pass.

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 todos and fixing.")

The subagent will: 1. Identify pages affected by the PR 2. Navigate to each page and capture snapshots (using Playwright MCP or 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 todos 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 /xcode-test 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 todos for any failures 9. Fix and retry until all tests pass

Standalone: /xcode-test [scheme]

8. Codify Decision Gate

After code review is complete and todos are created, present the Codify decision:

✅ Code Review Complete

**What should we codify from this work?**

1. **Document solution** - Run `/vt-c-compound` (if non-trivial problem solved)
2. **Extract skill** - Create new learning skill from patterns discovered
3. **Update existing skill** - Add patterns to existing skill references
4. **Promote pattern** - Add to Required Reading (critical patterns)
5. **Skip** - No codification needed
6. **Multiple** - Run multiple codification steps

**Decision Logic Hints:**
- If PR contains bug fixes → Consider Option 1
- If PR introduces new domain knowledge → Consider Option 2
- If PR refines existing patterns → Consider Option 3
- If P1 findings revealed critical pattern → Consider Option 4

Handle User Response:

Option 1: Document solution

# Launch compound-docs skill with PR context
Task general-purpose("Document the solution from PR #{pr_number} using /vt-c-compound. Extract the problem, investigation steps, root cause, and solution from the PR changes and review findings.")

Option 2: Extract skill

# Launch skill-extractor agent
Task skill-extractor("Analyze PR #{pr_number} for skill extraction opportunities. Check if patterns should become a new learning skill.")

Option 3: Update existing skill

  • Prompt: "Which skill? (provide name or describe domain)"
  • Search for matching skill in skills/
  • Add relevant patterns to skill's references/ directory
  • Confirm: "✓ Updated {skill-name} with patterns from PR #{pr_number}"

Option 4: Promote pattern

  • Extract critical pattern from PR findings
  • Add to docs/solutions/patterns/cora-critical-patterns.md
  • Use format: ❌ WRONG vs ✅ CORRECT
  • Log to metrics/pattern-promotions.json with auto_promoted: false
  • Confirm: "✓ Added to Required Reading as Pattern #{number}"

Option 5: Skip

  • Return to main workflow
  • No codification needed for this PR

Option 6: Multiple

  • Execute multiple options selected by user
  • Run in sequence

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. ```