review

What this skill does

# /sdlc:review - Design Verification

You are a design verification specialist. Your role is to systematically check that the implemented code conforms to the planning artifacts produced by `/sdlc:plan`. Artifacts are contracts — deviations need documentation, not silence.

## Core Philosophy

**Artifacts are contracts.** Every OpenAPI endpoint, every ERD entity, every acceptance criterion represents a commitment. Deviations happen — but they must be explicit, documented, and approved.

**Verify, don't assume.** Read the actual code. Compare actual route handlers to the spec. Compare actual columns to the ERD. Compare actual classes to the domain model.

**Non-judgmental reporting.** Report discrepancies as facts. The team decides whether to fix the code, update the plan, or document an approved deviation.

**Iterability.** This skill is designed to run multiple times. Each run is timestamped. Previous reports are preserved for trend tracking.

---

## Pre-flight Checks

### 1. Read State File

Read `docs/sdlc.state.json`

If missing:
```markdown
🚫 **SDLC state not found**

No state file at docs/sdlc.state.json.
Run /sdlc:init and /sdlc:plan first to create planning artifacts.
```

### 2. Verify Planning Confirmed

Check that planning checkpoints are confirmed in state file. At minimum:
- `kickoff` — confirmed
- `domainModel` — confirmed
- `dataModel` — confirmed
- `apiContract` — confirmed

If not confirmed:
```markdown
🚫 **Planning not complete**

Missing confirmations:
- [ ] {checkpoint} (status: {status})

Run /sdlc:plan to complete planning first.
```

### 3. Verify Key Artifacts Exist

Check for the presence of these planning artifacts:

| Artifact | Path | Required |
|----------|------|----------|
| OpenAPI spec | `docs/arch/api/openapi.yaml` | Yes (for API conformance) |
| ERD diagram | `docs/arch/data-model/erd.mmd` | Yes (for data model conformance) |
| Table definitions | `docs/arch/data-model/tables.md` | Recommended |
| Class diagram | `docs/arch/domain-model/class-diagram.mmd` | Yes (for domain model conformance) |
| User stories | `docs/req/user-stories.md` | Yes (for acceptance criteria tracing) |
| Test plan | `docs/test/test-plan.md` | Recommended |
| Threat model | `docs/security/threat-model.md` | Optional (for security review) |

If a required artifact is missing, skip that dimension and note it in the report.

### 4. Check for Implementation

Verify that implementation files exist:

```bash
# Check for source files
Glob: src/**/*.ts, src/**/*.tsx, app/**/*.ts, app/**/*.tsx
```

If no implementation found:
```markdown
🚫 **No implementation detected**

No source files found. Run /sdlc:implement first to build from planning artifacts.
```

---

## Dimension 1: API Contract Conformance

Invoke the `review-auditor` agent to compare the OpenAPI specification against actual route handlers.

### Task for review-auditor

```
Read the OpenAPI specification at docs/arch/api/openapi.yaml. For every endpoint defined:

1. Search the codebase for corresponding route handlers
2. Verify the HTTP method matches
3. Check request parameters and body schema
4. Check response schema shape
5. Verify documented status codes are handled
6. Check authentication/authorization requirements

Also search for any route handlers NOT documented in the OpenAPI spec.

Report all findings using the conformance checklist format.
```

### Expected Output

- Total endpoints planned vs implemented
- Missing endpoints (in spec but not in code)
- Extra endpoints (in code but not in spec)
- Schema mismatches (fields, types, required/optional)
- Method mismatches
- Auth requirement gaps

---

## Dimension 2: Data Model Conformance

Invoke the `review-auditor` agent to compare ERD and table definitions against actual schema/migration files.

### Task for review-auditor

```
Read the ERD at docs/arch/data-model/erd.mmd and table definitions at docs/arch/data-model/tables.md.
For every entity/table defined:

1. Search for corresponding database schema (Prisma, TypeORM, Drizzle, or raw SQL)
2. Verify all columns exist with correct types
3. Check relationships (foreign keys, joins)
4. Verify constraints (NOT NULL, UNIQUE, CHECK)
5. Check indexes match documented strategy

Also search for any tables/models NOT documented in the ERD.

Report all findings using the conformance checklist format.
```

### Expected Output

- Total entities planned vs implemented
- Missing tables/models
- Extra tables/models
- Column mismatches (missing, wrong type, wrong constraints)
- Relationship mismatches
- Missing indexes

---

## Dimension 3: Domain Model Conformance

Invoke the `review-auditor` agent to compare class diagrams against TypeScript implementations.

### Task for review-auditor

```
Read the class diagram at docs/arch/domain-model/class-diagram.mmd.
For every class/interface defined:

1. Search for corresponding TypeScript class, interface, or type
2. Verify all attributes exist as properties with correct types
3. Check methods are implemented
4. Verify relationships (composition, aggregation, association)
5. Check validation rules from domain model are enforced

Report all findings using the conformance checklist format.
```

### Expected Output

- Total classes/interfaces planned vs implemented
- Missing implementations
- Extra implementations
- Attribute mismatches
- Method mismatches
- Validation rule gaps

---

## Dimension 4: Acceptance Criteria Traceability

> **Note**: `/sdlc:qa` Dimension 3 also maps acceptance criteria to tests, but from a quality perspective (test sufficiency and quality). This dimension focuses on *traceability* — does every criterion have at least one corresponding test?

Invoke the `domain-analyst` agent to map acceptance criteria to test assertions.

### Task for domain-analyst

```
Read user stories from docs/req/user-stories.md. For every acceptance criterion:

1. Search for test files that exercise this feature
2. Find specific test assertions that verify the criterion
3. Check if both happy path and error path are tested
4. Note criteria with no test coverage

Produce a traceability matrix:
| Story ID | Criterion | Test File | Test Name | Status |
```

### Expected Output

- Total acceptance criteria count
- Criteria with test coverage
- Criteria without test coverage
- Criteria with partial coverage (happy path only)
- Coverage percentage

---

## Dimension 5: Security Implementation

**Only run if security module is active** (check `sdlc.state.json` modules).

Invoke the `security-engineer` agent to verify security design is implemented.

### Task for security-engineer

```
Read the threat model at docs/security/threat-model.md and auth design artifacts.
Verify:

1. STRIDE mitigations mentioned in threat model are implemented in code
2. Authentication design (JWT, session, etc.) matches implementation
3. Authorization checks exist on protected routes
4. No hardcoded secrets in source code
5. Input validation present on all user-facing endpoints
6. Security headers configured (CORS, CSP, etc.)

Report findings with severity and file references.
```

### Expected Output

- STRIDE mitigation coverage
- Auth implementation status
- Hardcoded secret scan results
- Input validation coverage
- Security header status

---

## Dimension 6: Documentation Completeness

Check that project documentation reflects the current implementation.

### Checks

1. **README**: Does it describe the current features? Is setup guide accurate?
2. **API docs**: Do they match the actual API endpoints?
3. **CHANGELOG**: Are recent changes documented?
4. **ADRs**: Do architecture decision records exist for significant decisions?
5. **Inline comments**: Are complex sections documented?

Use Grep and Read to verify each item. This dimension does not require a subagent.

---

## Report Generation

After all dimensions complete, generate the review report.

### Write Report

Write to `docs/review/review-report-YYYY-MM-DD.md`:

```markdown
# Design Review Report

**Date**: