deep-review

# 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

```bash
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"
git fetch origin "$BASE" --quiet 2>/dev/null || true
echo "=== DIFF STATS ==="
git diff "origin/$BASE" --stat
echo "=== CHANGED FILES ==="
git diff "origin/$BASE" --name-only
echo "=== DIFF SIZE ==="
git diff "origin/$BASE" --shortstat
```

Store the BASE branch name and list of changed files. You'll need them in every subsequent step.

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.

### 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 |

**Minimum**: always select at least 2 competencies.
**Maximum**: cap at 5 for diffs under 200 lines. All 8 allowed for 200+ lines.

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

```bash
git diff "origin/$BASE"
```

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.

### 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 job is {COMPETENCY} — ignore everything else.

## Changed files to review
{list each relevant file path}

Read each file listed above using the Read tool. Then apply this checklist:

## Checklist
{CHECKLIST from competency definitions below}

## Output format
For EACH finding, output exactly:

FINDING: {one-line description}
FILE: {path}:{line}
SEVERITY: CRITICAL | HIGH | MEDIUM | LOW
EVIDENCE: {quote the problematic code, max 3 lines}
FIX: {concrete fix suggestion, not vague advice}
CONFIDENCE: HIGH | MEDIUM | LOW

If you find NOTHING — output: "NO_FINDINGS — {COMPETENCY} review clean."

Do NOT pad with compliments. Do NOT report things that are fine. Only problems.
```

### Competency checklists

Use the checklist content from the files in `competencies/` directory. Read each relevant file before constructing the agent prompt.

If competency files don't exist yet, use the inline checklists below:

**security**:
- SQL/NoSQL injection (parameterized queries?)
- XSS (user input escaped in output?)
- Auth bypass (middleware on all protected routes?)
- CSRF (tokens validated?)
- Secrets in code (API keys, passwords, tokens hardcoded?)
- Trust boundary violations (LLM/external output used unsanitized?)
- Path traversal (user-controlled file paths?)
- Rate limiting on sensitive endpoints?
- CORS configuration (too permissive?)
- JWT validation (expiry, algorithm, issuer checked?)

**performance**:
- N+1 queries (loop with DB call inside?)
- Missing indexes on filtered/joined columns?
- Unbounded queries (no LIMIT on user-facing endpoints?)
- Memory leaks (event listeners not cleaned up? growing collections?)
- Bundle impact (new dependencies? tree-shaking?)
- Caching opportunities missed?
- Expensive operations in hot paths?
- Pagination on list endpoints?
- Image/asset optimization?

**architecture**:
- Separation of concerns (business logic in controllers?)
- Circular dependencies between modules?
- God objects/functions (>200 lines, >5 responsibilities?)
- Abstraction level consistency (mixing HTTP and business logic?)
- Interface contracts (types/schemas for cross-module communication?)
- DRY violations (copy-pasted logic that should be shared?)
- Layer violations (UI calling DB directly?)
- Configuration vs hardcoding?

**database**:
- Migration safety (reversible? data-preserving? locks?)
- Query performance (JOINs, subqueries, full table scans?)
- Transaction boundaries (operations that should be atomic?)
- Data integrity (constr