# Code Review

> Parallel multi-agent code review. Launch reviewer team, synthesize findings, auto-fix blocking issues, loop until clean. Use when: "review this", "code review", "is this ready to ship", "check this code", "review my changes". Trigger: /code-review, /review, /critique.

- Skill: `vril-labs/code-review-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add vril-labs/code-review-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/vril-labs/code-review-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: VRIL-LABS (https://skillmd.com/u/vril-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/vril-labs/code-review-2

---


# /code-review

Launch a parallel team of reviewers. Synthesize findings. Fix blocking issues
automatically. Loop until clean or escalate to human.

## Architecture

Five sub-agents in parallel, each with a distinct lens:

- **critic** — generalist evaluator, grades against criteria below
- **ousterhout** — deep modules, information hiding, interface simplicity
- **carmack** — pragmatic shippability, over-engineering detection
- **grug** — complexity hunting, layer counting
- **beck** — TDD quality, one behavior per test, red-green-refactor

Optional external reviewers: Think Tank CLI, Cerberus CLI.

## Workflow

### 1. Gather the diff

Get the diff via `git diff main...HEAD` or the specified scope.

### 2. Launch all reviewers in parallel

Spawn all five sub-agents simultaneously in a single message. Give each the
full diff and relevant codebase context. Each reviewer should return:
- **Ship / Don't Ship** verdict
- Top 3 concerns (file:line + specific fix)
- One sentence: best thing about this code

If the harness limits concurrency, run the critic first, then the four
philosophy agents in parallel, or run all sequentially as a fallback.

### 3. Synthesize

Collect all verdicts. Deduplicate overlapping concerns. Rank by severity.

### 4. Live Verification

If the change has user-facing components, the critic should verify the
implementation actually works — not just that it reads well.

- **Web:** Navigate to affected pages, exercise the feature, check for
  console errors and broken UI.
- **API:** Hit the changed endpoints, verify responses match the spec.
- **CLI:** Run the commands, verify output matches expectations.

If live verification fails, it's a blocking issue — treat as Don't Ship.
Skip for pure refactors, config changes, or library work with no runtime.

### 5. Gate

- **All Ship** → approve, proceed to merge
- **Any Don't Ship** → spawn a builder sub-agent for each blocking concern,
  giving it the specific file:line and fix instruction. Builder fixes, runs
  tests. Then re-review (return to step 2). Max 3 iterations.

### 6. Escalate

If still blocked after 3 iterations, report all findings to the user.
The issue needs human judgment.

## Grading Criteria

The critic applies structured grading (adapt per project):

| Criterion | Weight | Measures |
|-----------|--------|----------|
| **Correctness** | 30% | Tests pass? Edge cases? Does it actually work? |
| **Depth** | 25% | Deep modules with simple interfaces, or shallow pass-throughs? |
| **Simplicity** | 25% | Minimum complexity? Would you add or delete? |
| **Craft** | 20% | Error handling, naming, consistency with codebase |

Weight correctness and depth higher — models score well on craft by default
but underperform on architectural depth and actual correctness.

### Plausible-but-Wrong Patterns

LLMs optimize for plausibility, not correctness. Reviewers must actively
hunt for code that *looks right* but isn't:
- Wrong algorithm complexity (O(n²) where O(log n) is needed)
- Unnecessary abstractions (82K lines vs 1-line solution)
- Stub implementations that pass tests but don't actually work
- "Specification-shaped" code — right module names, wrong behavior
- Missing invariant checks that only matter at scale

## Simplification Pass

After review passes, if diff > 200 LOC net:
- Look for code that can be deleted
- Collapse unnecessary abstractions
- Simplify complex conditionals
- Remove compatibility shims with no real users

## Output

```markdown
## Code Review Summary

**Verdict:** Ship / Don't Ship / Escalated

### Findings
| Severity | File:Line | Issue | Fix |
|----------|-----------|-------|-----|
| blocking | src/auth.ts:42 | Leaky abstraction | Extract to module |

### Reviewer Consensus
- critic: Ship
- ousterhout: Ship
- carmack: Don't Ship — over-engineered auth layer
- grug: Ship
- beck: Ship

### Iterations: 2 (fixed auth layer on iteration 2)
```

## Gotchas

- **Self-review leniency:** Models consistently overrate their own work. The critic must be a separate sub-agent, not the builder evaluating itself.
- **Reviewing the whole codebase:** Review the diff, not the repo. `git diff main...HEAD` is the scope.
- **Vague feedback:** "Needs improvement" is useless. Every concern must have file:line + specific fix.
- **Infinite loop:** Cap at 3 review iterations. If still blocked, escalate — the issue needs human judgment.
- **Skipping the bench:** Running only the critic misses structural issues. The philosophy agents add perspectives the critic doesn't cover.
- **Treating all concerns equally:** Blocking issues (correctness, security) gate shipping. Style preferences don't.