---
name: review-spec
type: workflow
description: "Reviews a product, technical, API, UI, or implementation spec for completeness, testability, architectural fit, and readiness before planning or implementation."
argument-hint: "[path-to-spec-or-spec-summary]"
user-invocable: true
allowed-tools: Read, Glob, Grep
context: fork
effort: 3
agent: technical-director
when_to_use: "Use before turning a spec into a plan, when validating an externally supplied spec, when code review finds spec ambiguity, or when the user asks whether a spec is ready."
Review Spec
Purpose
review-spec validates whether a specification is strong enough to become the
source of truth for planning, TDD, implementation, and verification. It is a
read-only quality gate. It does not write code and it does not approve execution
by itself.
Use this workflow to prevent weak specs from becoming precise-looking plans with
hidden ambiguity.
Core Rule
No implementation plan from an unreviewed or materially ambiguous spec.
If the spec cannot be tested, reviewed against code, or handed to another agent
without guessing, return CHANGES REQUIRED.
Workflow
1. Identify the Source of Truth
- Locate the spec file, issue, PRD section, conversation summary, or design doc.
- Read only the surrounding context needed to understand the feature boundary.
- If no spec exists, stop and route to
spec-driven-development.
- If the current code appears to contradict the spec, stop and route to
spec-evolution instead of silently reviewing only one side.
2. Classify the Spec
Classify the spec as one or more:
- Product behavior
- Technical architecture
- API/data contract
- UI/UX flow
- Test/verification contract
- Release or migration plan
Use the classification to decide which checks matter most. For example, an API
spec must define request/response contracts and error behavior; a UI spec must
define states, accessibility requirements, and responsive behavior.
3. Review Against the Readiness Checklist
Evaluate the spec using these criteria:
| Area |
Required standard |
| Objective |
One clear outcome, user/system value, and non-goals |
| Scope |
Explicit in-scope and out-of-scope boundaries |
| Behavior |
Observable acceptance criteria, including failure states |
| Contracts |
API, data, events, files, or UI state contracts are concrete |
| Architecture |
Fits existing patterns or names required ADR/escalation |
| Dependencies |
Upstream/downstream dependencies and ordering are known |
| Verification |
Commands, tests, build, lint, manual, or visual checks are named |
| Rollback |
Risk and rollback/disable path are stated for risky changes |
| Handoff |
Another agent can plan from it without inventing requirements |
4. Detect Ambiguity and Drift
Flag these as blocking unless explicitly out of scope:
- Acceptance criteria are subjective or not observable.
- Terms such as "fast", "robust", "simple", "appropriate", or "secure" are
used without measurable meaning.
- Data shape, API contract, permissions, errors, loading states, or empty states
are implied but not defined.
- The spec references files or systems that do not exist.
- The spec conflicts with README, PRD, ADRs, code conventions, or existing user
flows.
- Implementation has already diverged from the spec.
If drift is found, do not resolve it inside this workflow. Recommend
spec-evolution and name the exact mismatch.
5. Produce a Verdict
Use this exact verdict scale:
APPROVED: Ready for planning-and-task-breakdown or test-driven-development.APPROVED WITH NOTES: Minor non-blocking gaps remain; execution can proceed
if the notes are carried into the plan.CHANGES REQUIRED: The spec is not ready; revise before planning or code.ROUTE TO SPEC-EVOLUTION: The spec/code reality mismatch must be resolved
before planning, implementation, or review can continue.
Output Format
## Spec Review: [Spec Name]
**Source:** [file/path or request summary]
**Spec Type:** [product / technical / API / UI / verification / release]
**Readiness Score:** [X/9]
### Blocking Issues
- [Issue with exact section/file reference, or "None"]
### Non-Blocking Notes
- [Note, or "None"]
### Missing Acceptance Criteria
- [Specific missing criterion, or "None"]
### Verification Fit
[Whether the spec can be verified, with named commands/checks if present.]
### Drift Check
[No drift found / suspected drift / confirmed drift with exact mismatch.]
### Verdict
`APPROVED` | `APPROVED WITH NOTES` | `CHANGES REQUIRED` | `ROUTE TO SPEC-EVOLUTION`
Anti-Rationalizations
| Thought |
Required correction |
| "The spec is good enough; planning will clarify it." |
Planning should decompose decisions, not invent requirements. |
| "The code will reveal the details." |
Details discovered in code must be reflected through spec-evolution. |
| "This is only a small spec." |
Small specs still need observable acceptance criteria. |
| "The user knows what they mean." |
The agent executing the plan needs explicit, reviewable language. |
| "I can approve with obvious assumptions." |
List assumptions as blockers or notes. Do not hide them. |
Integration
- Use after
spec-driven-development when a spec needs a quality gate before
planning.
- Use before
planning-and-task-breakdown when the plan source is an existing
spec.
- Use during
code-review when implementation quality depends on ambiguous or
missing spec requirements.
- Route to
spec-evolution when implementation reality and the spec disagree.
1---2name: review-spec3description: ---4---5---6name: review-spec7type: workflow8description: "Reviews a product, technical, API, UI, or implementation spec for completeness, testability, architectural fit, and readiness before planning or implementation."9argument-hint: "[path-to-spec-or-spec-summary]"10user-invocable: true11allowed-tools: Read, Glob, Grep12context: fork13effort: 314agent: technical-director15when_to_use: "Use before turning a spec into a plan, when validating an externally supplied spec, when code review finds spec ambiguity, or when the user asks whether a spec is ready."16---1718# Review Spec1920## Purpose2122`review-spec` validates whether a specification is strong enough to become the23source of truth for planning, TDD, implementation, and verification. It is a24read-only quality gate. It does not write code and it does not approve execution25by itself.2627Use this workflow to prevent weak specs from becoming precise-looking plans with28hidden ambiguity.2930## Core Rule3132```text33No implementation plan from an unreviewed or materially ambiguous spec.34```3536If the spec cannot be tested, reviewed against code, or handed to another agent37without guessing, return `CHANGES REQUIRED`.3839## Workflow4041### 1. Identify the Source of Truth4243- Locate the spec file, issue, PRD section, conversation summary, or design doc.44- Read only the surrounding context needed to understand the feature boundary.45- If no spec exists, stop and route to `spec-driven-development`.46- If the current code appears to contradict the spec, stop and route to47 `spec-evolution` instead of silently reviewing only one side.4849### 2. Classify the Spec5051Classify the spec as one or more:5253- Product behavior54- Technical architecture55- API/data contract56- UI/UX flow57- Test/verification contract58- Release or migration plan5960Use the classification to decide which checks matter most. For example, an API61spec must define request/response contracts and error behavior; a UI spec must62define states, accessibility requirements, and responsive behavior.6364### 3. Review Against the Readiness Checklist6566Evaluate the spec using these criteria:6768| Area | Required standard |69| --- | --- |70| Objective | One clear outcome, user/system value, and non-goals |71| Scope | Explicit in-scope and out-of-scope boundaries |72| Behavior | Observable acceptance criteria, including failure states |73| Contracts | API, data, events, files, or UI state contracts are concrete |74| Architecture | Fits existing patterns or names required ADR/escalation |75| Dependencies | Upstream/downstream dependencies and ordering are known |76| Verification | Commands, tests, build, lint, manual, or visual checks are named |77| Rollback | Risk and rollback/disable path are stated for risky changes |78| Handoff | Another agent can plan from it without inventing requirements |7980### 4. Detect Ambiguity and Drift8182Flag these as blocking unless explicitly out of scope:8384- Acceptance criteria are subjective or not observable.85- Terms such as "fast", "robust", "simple", "appropriate", or "secure" are86 used without measurable meaning.87- Data shape, API contract, permissions, errors, loading states, or empty states88 are implied but not defined.89- The spec references files or systems that do not exist.90- The spec conflicts with README, PRD, ADRs, code conventions, or existing user91 flows.92- Implementation has already diverged from the spec.9394If drift is found, do not resolve it inside this workflow. Recommend95`spec-evolution` and name the exact mismatch.9697### 5. Produce a Verdict9899Use this exact verdict scale:100101- `APPROVED`: Ready for `planning-and-task-breakdown` or `test-driven-development`.102- `APPROVED WITH NOTES`: Minor non-blocking gaps remain; execution can proceed103 if the notes are carried into the plan.104- `CHANGES REQUIRED`: The spec is not ready; revise before planning or code.105- `ROUTE TO SPEC-EVOLUTION`: The spec/code reality mismatch must be resolved106 before planning, implementation, or review can continue.107108## Output Format109110```markdown111## Spec Review: [Spec Name]112113**Source:** [file/path or request summary]114**Spec Type:** [product / technical / API / UI / verification / release]115**Readiness Score:** [X/9]116117### Blocking Issues118- [Issue with exact section/file reference, or "None"]119120### Non-Blocking Notes121- [Note, or "None"]122123### Missing Acceptance Criteria124- [Specific missing criterion, or "None"]125126### Verification Fit127[Whether the spec can be verified, with named commands/checks if present.]128129### Drift Check130[No drift found / suspected drift / confirmed drift with exact mismatch.]131132### Verdict133`APPROVED` | `APPROVED WITH NOTES` | `CHANGES REQUIRED` | `ROUTE TO SPEC-EVOLUTION`134```135136## Anti-Rationalizations137138| Thought | Required correction |139| --- | --- |140| "The spec is good enough; planning will clarify it." | Planning should decompose decisions, not invent requirements. |141| "The code will reveal the details." | Details discovered in code must be reflected through `spec-evolution`. |142| "This is only a small spec." | Small specs still need observable acceptance criteria. |143| "The user knows what they mean." | The agent executing the plan needs explicit, reviewable language. |144| "I can approve with obvious assumptions." | List assumptions as blockers or notes. Do not hide them. |145146## Integration147148- Use after `spec-driven-development` when a spec needs a quality gate before149 planning.150- Use before `planning-and-task-breakdown` when the plan source is an existing151 spec.152- Use during `code-review` when implementation quality depends on ambiguous or153 missing spec requirements.154- Route to `spec-evolution` when implementation reality and the spec disagree.
tranhieutt