---
name: ao-review
description: "Unified code review skill with configurable depth. Use --depth quick for automated subagent reviews, standard for thorough post-implementation reviews, or deep for exhaustive senior-level reviews."
category: core
invokes: [ao-state, ao-task, ao-review-domain]
invoked_by: [ao-implementation, ao-worker]
state_files:
  read: [constitution.md, baseline.md, focus.json, issues/*.md, issues/references/*]
  write: [focus.json, issues/*.md]
references: [.ao/reference/code-review-framework.md]
params:
  depth: quick|standard|deep  # default: standard
---

# Code Review Skill

> **Credit**: Code review integration adapted from obra/superpowers by Jesse Vincent (MIT License).

> **Consolidation note**: This skill replaces the former ao-review (quick), ao-critical-review (standard), ao-code-review-comprehensive (deep), and ao-code-review-interactive skills. Archived originals in `.ao/skills/_archived/`.

## Purpose

Unified code review with configurable depth. Catches issues early (cheaper than debugging later) and ensures consistent quality across all tasks.

## Depth Parameter

| Depth | When to Use | Scope | Former Skill |
|-------|-------------|-------|-------------|
| `quick` | After each task during implementation | Small diffs, subagent-based, immediate feedback | ao-review |
| `standard` (default) | Post-implementation, before completion | Full correctness, security, performance, design | ao-critical-review |
| `deep` | PR reviews, quality audits, major refactors | Exhaustive senior-level review, all axes mandatory | ao-code-review-comprehensive |

**Usage:**
```
/ao-review                    # standard depth (default)
/ao-review --depth quick      # automated subagent review
/ao-review --depth deep       # exhaustive senior-level review
```

## Review Triggers

| Trigger | Default Depth | When |
|---------|---------------|------|
| After each task | quick | During implementation |
| After major feature | standard | Post-implementation |
| Before completion | standard | Final quality gate |
| Manual request | standard | On demand |
| PR review / audit | deep | Quality gates |

## Two-Stage Review Process

### Stage 1: Plan Compliance Review

**Check first** (only if Stage 1 passes):
```
Review: Does implementation match plan?

✓ All requirements met
✓ No extra features added
✓ Follows specified approach

Assessment: SPEC COMPLIANT ✓
```

**Critical issues block progress:**
- Plan non-compliance, wrong architecture, missing requirements

### Stage 2: Code Quality Review (only after spec compliance)

**Review categories:**

| Category | Definition | Action |
|----------|-----------|--------|
| **Critical** | Blocks progress, security, breaking changes | Must fix before continuing |
| **Important** | Should fix, quality issue | Fix before next task or on approval |
| **Minor** | Nice to have, suggestion | Optional, can defer |

## Review Dimensions

### All Depths: Core Checks

1. **Correctness** — Logic analysis, boundary conditions, state management
   - Does the code do what it claims?
   - All code paths reachable and correct?
   - Loop invariants maintained? Recursion terminates?
   - Empty inputs, single element, max values, off-by-one?

2. **Error Handling** — Failure cases, error propagation, cleanup
   - Every failure case handled?
   - Errors propagated appropriately?
   - Cleanup happens even on error (finally/defer)?
   - No swallowed exceptions?

### Standard + Deep: Extended Checks

3. **Security** — Input validation, injection, auth, secrets
   - User input validated and sanitized?
   - No hardcoded secrets or credentials?
   - Auth checks on every protected path?

4. **Performance** — Time/space complexity, resource management
   - Appropriate algorithms for data size?
   - Resources properly released?
   - No N+1 queries or unbounded loops?

5. **Design** — Separation of concerns, coupling, naming
   - Clear responsibilities per module?
   - Minimal coupling between components?
   - Names convey intent?

### Deep Only: Exhaustive Checks

6. **Problem Fit** — Does code solve the stated problem exactly? Assumptions explicit?
7. **Abstractions** — Every abstraction justified? Single-implementation interfaces flagged?
8. **Failure Modes** — Every failure pathway identified? Recovery defined?
9. **Edge Cases** — Concurrency, unicode, overflow, timezone, empty inputs
10. **Maintainability** — Cognitive load, dependency health, test quality

**Deep review mindset** (from code-review-comprehensive):
- Simplicity over abstraction
- Clarity over cleverness
- Reversibility over prediction
- Evidence over speculation

## Procedure

### Step 0: Check Preferences

Check `.ao/skills/ao-review/preferences.md` for project-specific settings:
```yaml
review_depth: standard    # default depth
include_security: yes     # always include security review
include_performance: yes  # always include performance review
review_solid: auto        # SOLID principles (yes/no/auto)
```

### 1) Load Context

```
Read:
  - Current issue from focus.json
  - Implementation plan from references/{ISSUE-ID}-impl-plan.md
  - Diff: BASE to HEAD changes
  - Plan compliance requirements
```

### 2) Dispatch Reviewer

**Quick depth:** Dispatch subagent with fresh context:
```
Subagent:
  - Fresh context, no pollution from implementation
  - Full diff analysis from BASE to HEAD
  - Plan compliance check + code quality
  - Categorize findings (Critical/Important/Minor)
```

**Standard depth:** Perform review directly:
```
Review all dimensions (1-5):
  - Logic analysis, boundary conditions
  - Error handling audit
  - Security check
  - Performance analysis
  - Design assessment
```

**Deep depth:** Exhaustive review (all 10 dimensions):
```
Review all dimensions (1-10):
  - All standard checks
  - Problem fit & requirement fidelity
  - Abstraction justification
  - Failure mode analysis
  - Edge case enumeration
  - Maintainability assessment

Output mode: report | issues | both (default: report)
Issue prefix: CR (Code Review)
```

### 3) API Detection (Standard + Deep)

Before finalizing review, check if project contains APIs:
```yaml
api_indicators:
  - OpenAPI/Swagger spec files
  - API framework patterns (FastAPI, Flask, Express, etc.)
  - Route decorators (@app.route, @router.get, etc.)
```

**If API detected:** invoke `ao-review-domain --domain api` and merge findings.

### 4) Present Results

```
Review Results (depth: {depth}):

✓ Strengths: [list positive findings]
⚠ Important: [list items that should be fixed]
• Minor: [list suggestions]

Assessment: [APPROVED / REJECTED]
```

### 5) Update Issue Notes

Track all reviews in issue notes with date, depth, findings, assessment.

### 6) Interactive Comment Tracking (Optional)

For interactive review sessions (absorbed from ao-code-review-interactive):

Reviews stored in `.agent/ops/reviews/`:
```
.agent/ops/reviews/
├── YYYY-MM-DD-<short_hash>.md    # Review for specific commit
├── active-review.md               # Currently open review
```

Comment format:
```
### [CATEGORY] File:Line — Comment Title
Category: fix | question | suggestion | concern | praise
Status: open | addressed | wont_fix | deferred
Priority: critical | high | normal | low
```

## GitHub Integration

```bash
/ao-review --create-pr --title "Fix authentication flow"
/ao-review --pr 42 --post-comment
```

## Configuration

**Review strictness:**
- `strict` — All findings must be addressed
- `balanced` (default) — Important must be fixed, Minor optional
- `lenient` — Critical only, others optional

## Review Templates

Use templates in `.ao/skills/ao-review/templates/`:
- `plan-compliance.md` — Stage 1 review checklist
- `code-quality.md` — Stage 2 review checklist
