---
name: ao-review-domain
description: "Domain-specific code reviews. Use --domain to select: api (endpoint audit), docker (Dockerfile optimization), or meta (existential artifact justification)."
category: analysis
invokes: [ao-state, ao-task]
invoked_by: [ao-review]
state_files:
  read: [constitution.md, baseline.md, focus.json, issues/*.md]
  write: [focus.json, issues/*.md]
params:
  domain: api|docker|meta  # required
---

# Domain-Specific Code Review

> **Consolidation note**: This skill replaces the former ao-api-review (api), ao-docker-review (docker), and ao-existential-review (meta) skills. Archived originals in `.ao/skills/_archived/`.

## Purpose

Perform domain-specific reviews that require specialized knowledge beyond general code quality. Each domain has its own checklist, patterns, and output format.

## Domain Parameter

| Domain | When to Use | Former Skill |
|--------|-------------|-------------|
| `api` | Project contains API endpoints | ao-api-review |
| `docker` | Project contains Dockerfiles | ao-docker-review |
| `meta` | Challenge artifact existence (YAGNI audit) | ao-existential-review |

**Usage:**
```
/ao-review-domain --domain api       # API delivery audit
/ao-review-domain --domain docker    # Dockerfile optimization
/ao-review-domain --domain meta      # Existential artifact review
```

---

## Domain: API

> Platform/language agnostic API delivery and correctness auditor.

### Triggers

- `ao-review` detects API patterns in project (auto-invoked)
- Manual request for API audit
- Before API-related PR merge

### API Detection

```yaml
api_indicators:
  - OpenAPI/Swagger spec (openapi.yaml, swagger.json)
  - API framework patterns (FastAPI, Flask, Express, ASP.NET)
  - Route decorators (@app.route, @router.get, [HttpGet])
  - API test files (test_api_*, *_api_test.*)
```

### Review Checklist

| Area | Check |
|------|-------|
| **Contract** | Endpoints match OpenAPI spec? Response schemas correct? |
| **Behavior** | Success + failure paths tested? Edge cases handled? |
| **Security** | Auth on protected routes? Input validation? Rate limiting? |
| **Error Handling** | Consistent error format? Proper HTTP status codes? |
| **Versioning** | API version strategy defined? Breaking changes flagged? |
| **Documentation** | Endpoints documented? Examples provided? |

### Output Format

```
API Review: {project}

Endpoints Audited: {count}
Contract Compliance: {pass/fail}

Findings:
  Critical: {list}
  Important: {list}
  Minor: {list}

Assessment: {PASS / FAIL}
```

### Reference

See `.ao/references/api-guidelines.md` for the full API development checklist.

---

## Domain: Docker

> Dockerfile analysis for best practices, security, and optimization.

### Modes

| Mode | Command | Purpose |
|------|---------|---------|
| Review | `--domain docker` | Analyze existing Dockerfile |
| Optimize | `--domain docker --optimize` | Suggest changes with before/after |
| Build | `--domain docker --build` | Interactive Dockerfile creation |

### Review Checklist

| Area | Check |
|------|-------|
| **Base Image** | Minimal base? Pinned version? Official image? |
| **Layers** | Optimized layer ordering? Combined RUN commands? |
| **Security** | Non-root user? No secrets in image? Minimal attack surface? |
| **Size** | Multi-stage build? .dockerignore present? Unnecessary files excluded? |
| **Caching** | Dependencies installed before code copy? Cache-friendly ordering? |
| **Health** | HEALTHCHECK defined? Graceful shutdown handled? |

### Output Format

```
Docker Review: {Dockerfile}

Image Size Estimate: {size}
Security Issues: {count}
Optimization Opportunities: {count}

Findings:
  Critical: {list}
  Important: {list}
  Minor: {list}

Optimized Dockerfile: (if --optimize)
```

---

## Domain: Meta (Existential Review)

> Challenge every artifact's right to exist. Force explicit justification.

### Purpose

Code generation is easy. Code *interrogation* is hard. This domain ensures artifacts earn their existence.

### Trigger

- After implementation completes (optional)
- During deep review (on demand)
- During retrospective (optional)
- Standalone YAGNI audit

### The Existential Questions

For each artifact (file, module, abstraction, feature):

1. **Why does this exist?** — What problem does it solve today?
2. **Who uses this?** — Grep for actual usage. Zero callers = candidate for removal.
3. **What happens without it?** — Would anything break? Would anyone notice?
4. **Is there a simpler alternative?** — Could this be inlined, merged, or eliminated?
5. **Does this earn its complexity?** — Is the abstraction worth the cognitive cost?

### Output Format

```
Existential Review: {scope}

Artifacts Reviewed: {count}
Justified: {count}
Questionable: {count}
Recommended for Removal: {count}

Findings:
  Remove: {list with justification}
  Simplify: {list with suggestion}
  Keep: {list — earned their existence}
```

### Red Flags

- Files with zero imports/references
- Abstractions with single implementation
- Features with no tests and no documented users
- "Just in case" code with no concrete use case
- Wrappers that add no value over the wrapped API
