/deep-review

name: deep-review
metadata:
  version: "1.0.0"
description: |
  Parallel competency-based code review. Launches independent Agent reviewers per competency
  (security, performance, architecture, database, concurrency, error-handling, frontend, testing),
  each with a focused checklist and isolated context. Synthesizes findings into unified report
  with FIX/DEFER/ACCEPT triage. Use when: "deep review", "thorough review", "parallel review",
  "review by competency", "full code review", or for large diffs (200+ lines) where /review
  may be too shallow. Complements /review (pre-landing) — this is for deep dives. Do NOT use just to
  orient in an unfamiliar codebase or get a structural symbol overview; use repo-map
  for that (this audits a concrete diff for defects, it is not a navigation map).
  Review is read-only unless the user explicitly asks to review and fix.
allowed-tools:
  - Bash
  - Read
  - Edit
  - Grep
  - Glob
  - Agent
  - AskUserQuestion
  - TodoWrite

Deep Review — Parallel Competency-Based Code Review

Inspired by Memento workflow engine's parallel review pattern. Philosophy: one focused expert per domain > one generalist checking everything.

---

Step 0: Determine scope

BASE=$(gh pr view --json baseRefName -q .baseRefName 2>/dev/null || git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@refs/remotes/origin/@@' || echo "main")
echo "BASE: $BASE"
BASE_REF=$(git rev-parse --verify --quiet "refs/remotes/origin/$BASE" 2>/dev/null || git rev-parse --verify --quiet "$BASE" 2>/dev/null || true)
if [ -z "$BASE_REF" ]; then
  echo "No locally available base ref for $BASE; cannot perform a read-only diff." >&2
  exit 2
fi
echo "BASE_REF: $BASE_REF"
echo "=== DIFF STATS ==="
git diff "$BASE_REF" --stat
echo "=== CHANGED FILES ==="
git diff "$BASE_REF" --name-only
echo "=== DIFF SIZE ==="
git diff "$BASE_REF" --shortstat

Store the BASE branch name, resolved local base ref, and list of changed files. Report-only review does not run `git fetch`, `pull`, or another command that updates Git state. If the accepted task explicitly requires a fresh remote base and permits that preparation mutation, run `git fetch origin "$BASE" --quiet` without suppressing failure before resolving `BASE_REF`; otherwise state that the review used the locally available ref.

If there is no diff, stop: "Nothing to review — no changes against $BASE."

---

Step 1: Scoping — select relevant competencies

Based on the changed files, select ONLY the competencies that are relevant. Do NOT run all 8 for a 3-file CSS change.

Default to a review-only task. Enter review-and-fix only when the user clearly authorizes both review and implementation (for example, "review and fix"). In either mode, the review phase remains read-only; review-and-fix continues with the approved remediation in this same task after findings are triaged.

Competency selection rules

| Competency | Trigger files/patterns | |---|---| | **security** | auth, middleware, routes handling user input, env files, CORS, JWT, crypto, passwords, tokens, API keys | | **performance** | database queries, loops over collections, API endpoints, bundle config, image/asset handling, caching | | **architecture** | new files/modules, cross-module imports, service boundaries, DI patterns, >5 files changed | | **database** | migrations, schema changes, raw SQL, ORM queries, transactions, indexes | | **concurrency** | queues, workers, locks, async/await patterns, shared state, cron jobs, webhooks | | **error-handling** | try/catch blocks, error responses, validation, external API calls, file I/O | | **frontend** | Vue/React components, CSS/Tailwind, composables/hooks, stores, routing, i18n | | **testing** | test files changed OR >100 lines of logic changed without test changes |

Select every materially relevant competency and no others. Diff size is a signal to inspect scope, not a reason to add unrelated reviewers. A single competency is valid when the changed risk has one material dimension.

Output the selected competencies with a one-line justification each:

Selected competencies (4 of 8):
  ✓ security — auth middleware modified
  ✓ database — new migration + 3 query changes
  ✓ concurrency — BullMQ worker modified
  ✓ error-handling — 4 new try/catch blocks in API routes
  ✗ architecture — no new modules, existing patterns
  ✗ performance — no hot paths touched
  ✗ frontend — no UI changes
  ✗ testing — test files updated alongside logic

---

Step 2: Get the diff content

git diff "$BASE_REF"

Read the full diff. You need it to construct focused prompts for each competency agent.

Also identify which files are relevant to each selected competency — each agent should receive ONLY the files relevant to its domain, not the entire diff.

---

Step 3: Launch parallel competency reviews

For each selected competency, launch an Agent tool call **in parallel**. Each agent:

• Gets ONLY the files relevant to its competency
• Has a focused checklist (from the competency definitions below)
• Returns findings in structured format
• Works in isolated context (no bias from other competency reviews)

**CRITICAL**: Launch ALL agents in a SINGLE message (parallel tool calls). Do NOT launch them sequentially.

If a reviewer must run tests, give it an isolated writable worktree and a unique writable scratch directory. Capture `git status --porcelain=v1`, `git diff --exit-code`, and `git diff --cached --exit-code` before and after the review. Do not place a test-running reviewer in an OS-level read-only sandbox: pytest and similar tools legitimately create temporary files. If only a strict read-only sandbox is available, provide immutable test receipts for inspection and say that the reviewer did not execute the tests.

Agent prompt template

For each competency, use this prompt structure (fill in {COMPETENCY}, {CHECKLIST}, {FILES}):

You are a {COMPETENCY} specialist reviewing code changes. Your ONLY