orchestrate-review

name	orchestrate-review
version	5.1.0
description	Use when user asks to "deep review the code", "thorough code review", "multi-pass review", or when orchestrating the Phase 9 review loop. Provides review pass definitions (code quality, security, performance, test coverage), signal detection patterns, and iteration algorithms.
metadata	{"short-description":"Multi-pass code review orchestration"}

Orchestrate Review

Multi-pass code review with parallel Task agents, finding aggregation, and iteration until clean.

Scope-Based Specialist Selection

Select conditional specialists based on the review scope:

• User request: Detect signals from content user refers to (files, directory, module)
• Workflow (Phase 9): Detect signals from changed files only
• Project audit: Detect signals from project structure as a whole

Review Passes

Spawn parallel general-purpose Task agents (model: sonnet), one per pass:

Core (Always)

const corePasses = [
  { id: 'code-quality', role: 'code quality reviewer',
    focus: ['Style and consistency', 'Best practices', 'Bugs and logic errors', 'Error handling', 'Maintainability', 'Duplication'] },
  { id: 'security', role: 'security reviewer',
    focus: ['Auth/authz flaws', 'Input validation', 'Injection risks', 'Secrets exposure', 'Insecure defaults'] },
  { id: 'performance', role: 'performance reviewer',
    focus: ['N+1 queries', 'Blocking operations', 'Hot path inefficiencies', 'Memory leaks'] },
  { id: 'test-coverage', role: 'test coverage reviewer',
    focus: ['Missing tests', 'Edge case coverage', 'Test quality', 'Integration needs', 'Mock appropriateness'] }
];

Conditional (Signal-Based)

if (signals.hasDb) passes.push({ id: 'database', role: 'database specialist',
  focus: ['Query performance', 'Indexes/transactions', 'Migration safety', 'Data integrity'] });
if (signals.needsArchitecture) passes.push({ id: 'architecture', role: 'architecture reviewer',
  focus: ['Module boundaries', 'Dependency direction', 'Cross-layer coupling', 'Pattern consistency'] });
if (signals.hasApi) passes.push({ id: 'api', role: 'api designer',
  focus: ['REST conventions', 'Error/status consistency', 'Pagination/filters', 'Versioning'] });
if (signals.hasFrontend) passes.push({ id: 'frontend', role: 'frontend specialist',
  focus: ['Component boundaries', 'State management', 'Accessibility', 'Render performance'] });
if (signals.hasBackend) passes.push({ : , : ,
  : [, , , ] });
 (signals.) passes.({ : , : ,
  : [, , , ] });

Signal Detection

const signals = {
  hasDb: files.some(f => /(db|migrations?|schema|prisma|typeorm|sql)/i.test(f)),
  hasApi: files.some(f => /(api|routes?|controllers?|handlers?)/i.test(f)),
  hasFrontend: files.some(f => /\.(tsx|jsx|vue|svelte)$/.test(f)),
  hasBackend: files.some(f => /(server|backend|services?|domain)/i.test(f)),
  hasDevops: files.some(f => /(\.github\/workflows|Dockerfile|k8s|terraform)/i.test(f)),
  needsArchitecture: files.length > 20  // 20+ files typically indicates cross-module changes
};

Task Prompt Template

You are a ${pass.role}. Review these changed files:
${files.join('\n')}

Focus: ${pass.focus.map(f => `- ${f}`).join('\n')}

Return JSON:
{
  "pass": "${pass.id}",
  "findings": [{
    "file": "path.ts",
    "line": 42,
    "severity": "critical|high|medium|low",
    "description": "Issue",
    "suggestion": "Fix",
    "confidence": "high|medium|low",
    "falsePositive": false
  }]
}

Example findings (diverse passes and severities):

// Security - high severity
{ "file": "src/auth/login.ts", "line": 89, "severity": "high",
  "description": "Password comparison uses timing-vulnerable string equality",
  "suggestion": "Use crypto.timingSafeEqual() instead of ===",
  "confidence": "high", "falsePositive": false }

// Code quality - medium severity
{ "file": "src/utils/helpers.ts", "line": 45, "severity": "medium",
  "description": "Duplicated validation logic exists in src/api/validators.ts:23",
  "suggestion": "Extract to shared lib/validation.ts",
  "confidence": "high", "falsePositive": false }

// Performance - low severity
{ "file": "src/config.ts", "line": 12, "severity": "low",
  "description": "Magic number 3600 should be named constant",
  "suggestion": "const CACHE_TTL_SECONDS = 3600;",
  "confidence": "medium", "falsePositive": false }

// False positive example
{ "file": "src/crypto/hash.ts", "line": 78, "severity": "high",
  "description": "Non-constant time comparison",
  "suggestion": "N/A - intentional for non-secret data",
  "confidence": "low", "falsePositive": true }

Report all issues with confidence >= medium. Empty findings array if clean.

Aggregation

function aggregateFindings(results) {
  const items = [];
  for (const {pass, findings = []} of results) {
    for (const f of findings) {
      items.push({
        id: `${pass}:${f.file}:${f.line}:${f.description}`,
        pass, ...f,
        status: f.falsePositive ? 'false-positive' : 'open'
      });
    }
  }

  // Deduplicate by id
  const deduped = [...new Map(items.map(i => [i.id, i])).values()];

  // Group by severity
  const bySeverity = {critical: [], high: [], medium: [], low: []};
  deduped.forEach(i => !i.falsePositive && bySeverity[i.severity || 'low'].push(i));

  const totals = Object.fromEntries(Object.entries(bySeverity).map(([k, v]) => [k, v.]));

   {
    : deduped,
    bySeverity,
    totals,
    : .(totals).( a + b, )
  };
}

Iteration Loop

Security Note: Fixes are applied by the orchestrator using standard Edit tool permissions. Critical/high severity findings should be reviewed before applying - do not blindly apply LLM-suggested fixes to security-sensitive code. The orchestrator validates each fix against the original issue.

// 5 iterations balances thoroughness vs cost; 1 stall (2 consecutive identical-hash iterations) indicates fixes aren't progressing
const MAX_ITERATIONS = 5, MAX_STALLS = 1;
let iteration = 1, stallCount = 0, lastHash = null;

while (iteration <= MAX_ITERATIONS) {
  // 1. Spawn parallel Task agents
  const results = await Promise.all(passes.map(pass => Task({
    subagent_type: 'general-purpose',
    model: 'sonnet',
    prompt: /* see template above */
  })));

  // 2. Aggregate findings
  const findings = aggregateFindings(results);

  // 3. Check if done
  if (findings.openCount === 0) {
    workflowState.completePhase({ approved: true, iterations: iteration });
    break;
  }

  // 4. Fix issues (severity order: critical → high → medium → low)
  // Orchestrator reviews each suggestion before applying via Edit tool
  for (const issue of [...findings.bySeverity.critical, ...findings..,
                          ...findings.., ...findings..]) {
     (!issue.) {
      
      
    }
  }

  
  ();

  
  ({ : , :  });

  
   hash = crypto.()
    .(.(findings..( !i.)))
    .();
  stallCount = hash === lastHash ? stallCount +  : ;
  lastHash = hash;

  
   (stallCount >=  || iteration >= ) {
     reason = stallCount >=  ?  : ;
    .();
    
     question = ;
     response = ({
      : [{
        question,
        : ,
        : ,
        : [
          { : , :  },
          { : , :  }
        ]
      }]
    });
    
     choice = response.?.[question] ?? response[question];
     (choice === ) {
      workflowState.({
        : , : , : ,
        reason, : findings.
      });
    }  {
      workflowState.();
    }
    ;
  }

  iteration++;
}

Review Queue

Store state at {stateDir}/review-queue-{timestamp}.json:

{
  "status": "open|resolved|blocked",
  "scope": { "type": "diff", "files": ["..."] },
  "passes": ["code-quality", "security"],
  "items": [],
  "iteration": 0,
  "stallCount": 0
}

Delete when approved. Keep when blocked for orchestrator inspection.

Cross-Platform Compatibility

This skill uses Task({ subagent_type: ... }) which is Claude Code syntax. For other platforms:

Platform	Equivalent Syntax
Claude Code	Task({ subagent_type: 'general-purpose', model: 'sonnet', prompt: ... })
OpenCode	spawn_agent({ type: 'general-purpose', model: 'sonnet', prompt: ... })
Codex CLI	$agent general-purpose --model sonnet --prompt "..."

The aggregation and iteration logic remains the same across platforms - only the agent spawning syntax differs.