codereview

name: codereview description: "Use when you need a comprehensive code review combining architecture, security, and test perspectives - especially before merging, releasing, or after major changes." user-invocable: true argument-hint: "[path, module, or PR]" allowed-tools: Read, Bash, Glob, Grep

/codereview - Multi-Reviewer Parallel Code Review

Run a comprehensive code review that dispatches 3 specialized perspectives concurrently - architecture, security, and testing - then consolidates into a single actionable verdict.

Target: $ARGUMENTS

Why 3 Perspectives, Not 6

Most multi-reviewer systems use 5-7 overlapping perspectives that waste tokens and produce redundant findings. /codereview uses exactly 3 orthogonal perspectives - each covers a distinct failure mode with zero overlap:

┌──────────────────────────────────────────────────────────────┐
│              PARALLEL REVIEW DISPATCH                        │
│                                                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ @reviewer   │  │ @security   │  │ @tester     │          │
│  │ Architecture│  │ OWASP/Auth  │  │ Coverage    │          │
│  │ + Quality   │  │ + Data      │  │ + Edge Cases│          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
│         │                │                │                  │
│         └────────────────┼────────────────┘                  │
│                          ▼                                   │
│                  ┌──────────────┐                             │
│                  │ CONSOLIDATE  │                             │
│                  │ Deduplicate  │                             │
│                  │ Assign Sev.  │                             │
│                  │ Verdict      │                             │
│                  └──────────────┘                             │
└──────────────────────────────────────────────────────────────┘

When to Use

• Before merging a pull request
• Before a production release
• After major refactors that touch multiple modules
• After new contributor PRs (unfamiliar with codebase conventions)
• When a change touches auth, payments, or data handling
• NOT for: quick single-file fixes (use @reviewer directly)
• NOT for: security-only audit (use @security directly)
• NOT for: test strategy design (use @tester directly)

Workflow

Step 1: Scope Detection

Determine the review target:

IF $ARGUMENTS is a file/directory path → review that path
IF $ARGUMENTS is a module name → find and review the module
IF $ARGUMENTS is a PR number/URL → extract changed files from PR diff
IF $ARGUMENTS is empty → review staged/uncommitted changes

Gather scope metrics:

# Count files and lines in scope
find $TARGET -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" \) | head -200 | xargs wc -l 2>/dev/null || true

# If PR, get the diff
gh pr diff $PR_NUMBER 2>/dev/null || git diff main...HEAD 2>/dev/null || true

Read the project's docs/ARCHITECTURE.md if it exists - this is the source of truth for architecture review.

Step 2: Parallel Review Dispatch

Dispatch 3 concurrent review perspectives. Each reviewer gets the full file context but applies a different lens.

Perspective 1: Architecture Review (@reviewer focus)

Review the code for structural integrity and quality:

# Architecture checks
grep -rn ": any\|as any" $TARGET --include="*.ts" --include="*.tsx" 2>/dev/null | head -20
grep -rn "console\.\|debugger" $TARGET --include="*.ts" --include="*.tsx" --include="*.vue" 2>/dev/null | head -20

Perspective 2: Security Review (@security focus)

Review the code for vulnerabilities and data safety:

# Security checks
npm audit --json 2>/dev/null | head -50 || true
grep -rn "password\|secret\|token\|api_key\|apikey" $TARGET --include="*.ts" --include="*.tsx" --include="*.env*" 2>/dev/null | head -20
grep -rn "v-html\|dangerouslySetInnerHTML\|innerHTML" $TARGET --include="*.ts" --include="*.tsx" --include="*.vue" 2>/dev/null | head -20
grep -rn "eval(\|new Function(" $TARGET --include="*.ts" --include="*.tsx" --include="*.js" 2>/dev/null | head -20

Perspective 3: Test Review (@tester focus)

Review the code for test quality and coverage:

# Test checks
find $TARGET -name "*.spec.ts" -o -name "*.test.ts" -o -name "*.spec.tsx" -o -name "*.test.tsx" 2>/dev/null | wc -l
npx vitest run --passWithNoTests --reporter=json 2>/dev/null || npx jest --json --passWithNoTests 2>/dev/null || true

Step 3: Consolidation

Merge findings from all 3 perspectives:

1. Deduplicate - Remove findings flagged by multiple perspectives (keep highest severity)
2. Cross-reference - A security finding that also lacks tests is escalated one severity level
3. YAGNI Check - For every new abstraction, interface, or utility introduced in the change:
   • Is it used in more than one place RIGHT NOW? (not "will be useful later")
   • Does it add configurability that isn't required by the current spec?
   • Does it introduce a layer of indirection without clear benefit?
   • Flag unnecessary abstractions as MEDIUM (over-engineering)
4. Observability Check - For code touching critical paths (auth, payments, data, API):
   • Structured logging present? (not just console.log)
   • Error tracking with context? (user, request, stack trace)
   • Health check endpoint if it's a new service?
   • Correlation IDs propagated across boundaries?
   • Flag missing observability as MEDIUM (or HIGH for auth/payments)
5. Assign severity - Every finding gets a severity level (see table below)
6. Sort - CRITICAL first, then HIGH, MEDIUM, LOW
7. Group - By file, then by severity within each file

Step 4: Verdict

Apply verdict rules based on the consolidated findings. The verdict is final and non-negotiable - it follows the rules mechanically.

Severity Levels

Verdict Rules

Escalation rules:

• A security finding without a corresponding test → severity +1 level
• A finding that recurs from a previous review → severity +1 level
• A finding in auth, payments, or PII handling → minimum severity HIGH
• A change touching observability/monitoring code without corresponding tests → severity +1 level
• A new abstraction used in only one place → flag as YAGNI (MEDIUM)

Verification Protocol

Before claiming the review is complete:

1. All 3 perspectives were executed (architecture, security, tests)
2. Every finding has a severity level assigned
3. Every CRITICAL or HIGH finding includes a specific file:line reference
4. Every CRITICAL or HIGH finding includes a concrete remediation suggestion
5. Automated checks were run where available (npm audit, tsc, linting, test suite)
6. The verdict follows the Verdict Rules mechanically - no exceptions
7. Cross-referencing was performed (security findings checked for test coverage)

Anti-Rationalization

Rules

1. All 3 perspectives are mandatory - Skipping one defeats the purpose of multi-reviewer review
2. Read-only - Never modify files during a review
3. Evidence required - Every finding needs a file:line reference and explanation
4. Remediation required - Findings without fix suggestions are useless
5. Verdict is mechanical - Follow the Verdict Rules table, no subjective overrides
6. No sycophancy - Never say "LGTM", "looks good", or "great job" without evidence
7. Cross-reference findings - A security issue without tests is worse than either alone
8. Severity must be justified - Every rating needs a specific technical reason
9. Run automated tools - Never skip npm audit, linting, or type checking if available
10. Fresh context per perspective - Each reviewer perspective starts from the code, not from another reviewer's output

Output

──── /codereview ────
Target: [path or PR]
Scope: [X files, Y lines]

Architecture: [N findings] - @reviewer
Security:     [N findings] - @security
Tests:        [N findings] - @tester

Severity:
  CRITICAL: N
  HIGH: N
  MEDIUM: N
  LOW: N

Top Findings:
1. [CRITICAL] [description] - [file:line]
2. [HIGH] [description] - [file:line]
3. [HIGH] [description] - [file:line]

Verdict: [APPROVE | APPROVE WITH NOTES | REQUEST_CHANGES | BLOCK]
Reason: [1-line justification]