Review Specifications

---
name: review-specifications
description: Review a technical specification for ambiguities, inconsistencies, incoherences, missing information, and implementability concerns.
---

# Review Specifications

Audits a technical specification and reports findings across seven categories: ambiguities, inconsistencies, incoherences, missing information, implementability, reversibility, and forward compatibility.

## Prerequisites

- Apply the shared SDLC conventions in `skills/sdlc/references/shared.md`.
- If no argument is provided, locate the feature directory under `.sdlc/features/` whose frontmatter `issue` field references `$ISSUE_NUMBER`.
- `.sdlc/features/N-<slug>/specification.md`, or a specification document provided in context or as a file path
- `.sdlc/features/N-<slug>/requirements.md` (optional, improves coverage analysis)

## Steps

1. Read the specification from `.sdlc/features/N-<slug>/specification.md` if present, otherwise from context or as a file path.
2. Cross-reference against the requirements document if available.
3. Run the deterministic checkers best-effort: lint `api.yaml` with `npx -y @stoplight/spectral-cli lint` and render each `mermaid` block with `mmdc` (or `npx -y @mermaid-js/mermaid-cli`) when available. A tool that is not installed is skipped (never blocks); a validation failure is a blocking finding under Inconsistencies.
4. Identify issues in each of the six categories below.
5. Report findings. Omit any category that has no findings.
6. Write the findings to `.sdlc/features/N-<slug>/review-specification.md` with frontmatter `artifact: specification`, `verdict` (`approved` if there are no blocking findings, `changes-requested` if the author must address findings, `rejected` for a fundamental flaw), and `reviewed_at: <ISO date>`, and the findings as the body, per `skills/sdlc/references/shared.md`. Record any unresolved open questions in the findings body. For any question that carries meaningful risk to the implementation, also invoke `/create-assumption` to record it formally.

## Review Checklist

### Ambiguities
- Are field names and types unambiguous?
- Are behavior descriptions precise (no "it should handle errors appropriately")?
- Are state transitions and edge-case handling clearly defined?

### Inconsistencies
- Do data models match the API contracts (field names, types)?
- Do data models and the summary table match `api.yaml` where it exists (field names, types, required flags, error codes)?
- Are field names consistent across endpoints and schemas?
- Do sequence diagrams match the described API behavior (messages correspond to real endpoints, responses match documented status codes)?
- Does every endpoint in `api.yaml` appear in a sequence or the summary table, and vice versa (no orphan operations)?

### Incoherences
- Do any stated technical decisions contradict each other?
- Is the architecture consistent with the stated constraints?
- Are there self-contradictory statements within a single section?

### Missing Information
- Are all requirements from the requirements document addressed?
- Are error cases and edge conditions handled?
- Are authentication and authorization requirements specified?
- Are performance targets and SLAs stated?

### Implementability
- Are there design choices that are impractical or unnecessarily complex?
- Are there circular dependencies or unresolvable constraints?
- Are external dependencies clearly defined with their interfaces?

### Reversibility
- Can we undo this cleanly, or does the spec commit to decisions that are hard to reverse?
- Are destructive data model changes, breaking API changes, and irreversible transformations called out explicitly?
- Do migrations and state transitions include a backward path or deprecation window?

### Forward Compatibility
- Can the data models and API contracts grow additively, or does the design lock in the current shape?
- Do consumers tolerate unknown fields and unknown enum values rather than rejecting them?
- Is a versioning strategy and compatibility policy (e.g., additive-only within a major version) stated?
- Are extension points reserved for known likely future change, or are fixed-set assumptions baked in?

## Output Format

```markdown
## Ambiguities

<Findings or "No issues found.">

## Inconsistencies

<Findings or "No issues found.">

## Incoherences

<Findings or "No issues found.">

## Missing Information

<Findings or "No issues found.">

## Implementability

<Findings or "No issues found.">

## Reversibility

<Findings or "No issues found.">

## Forward Compatibility

<Findings or "No issues found.">
```

## Outcome

If `$OUTCOME_YAML` is set, emit your verdict there per `skills/sdlc/references/shared.md`:

| Verdict | When |
|---|---|
| `approved` | No blocking findings; the subject passes review |
| `changes-requested` | Findings the author must address before it passes |
| `rejected` | Fundamental flaw requiring rework or stopping |

In the same emission, list the findings file under `artifacts:` (`.sdlc/features/N-<slug>/review-specification.md`).

## Example Usage

**Scenario 1: Mismatched schema**
API contract says `user_id: string` but data model defines `id: uuid`.
Report under Inconsistencies.

**Scenario 2: Unspecified auth**
Spec defines endpoints that modify user data but never mentions authentication or authorization rules.
Report under Missing Information.

**Scenario 3: Unnecessary complexity**
Spec requires a distributed lock for a feature that could use a simple DB transaction.
Report under Implementability.

**Scenario 4: OpenAPI lint failure**
`spectral lint api.yaml` reports an unresolved `$ref` and an operation without a response.
Report under Inconsistencies: the normative contract does not validate.

## Next Step

Once the findings verdict is `approved`, continue with `/create-lifecycle`.

## Useful Commands Reference

| Command | Description |
|---|---|
| `npx -y @stoplight/spectral-cli lint api.yaml` | Best-effort OpenAPI lint; failure is a blocking finding |
| `mmdc -i <diagram.mmd>` or `npx -y @mermaid-js/mermaid-cli` | Best-effort Mermaid render check; failure is a blocking finding |