| name | spec-review |
| description | Review whether current changes follow Spec Guided Dev rules. Use before commits or when checking spec structure. |
Spec review
Read:
docs/spec-guided-dev-method.md- relevant numbered current spec documents directly under
.specs/
- related
.specs/deviations/*.md documents when current implementation state matters
- current git diff
AGENTS.mdCLAUDE.md if present
Check:
- Does this change require a spec document?
- If yes, does the document exist?
- Is the type correct:
spec, adr, spike, or deviation?
- Is the numeric sequence correct across
.specs/ and .specs/archive/?
- Are current spec documents stored directly under
.specs/?
- Are archived spec documents stored under
.specs/archive/?
- Are deviation documents stored under
.specs/deviations/?
- Do spec document filenames avoid old lifecycle markers?
- Does
.specs/INDEX.md exist and reflect current numbered documents?
- Does every spec document have a title,
Type:, and Related: with document numbers or none?
- Does the document have required sections for its type?
- Are specs describing product intent rather than tasks?
- Are product-neutral changes kept out of
.specs?
- Are deviations temporary and separate from specs?
- Are resolved deviations deleted?
- Are archived specs excluded from current product intent?
- Are semantic changes not hidden as cleanup?
- Are shared specs represented as normal spec documents?
- If an old requirement or ADR changed, was the old document moved to
.specs/archive/ and the new current document given Replaces:?
- Are accepted ADRs and old requirements left semantically immutable?
Required section checks:
- Specs must have
Goal, Context, Scope, Non-goals, Specification, Acceptance criteria, and Verification.
- ADRs must have
Context, Options considered, Decision, and Consequences.
- Spikes must have
Goal, Hypothesis, Experiment, Constraints, Done criteria, Result, and Recommendation.
- Deviations must have related spec,
Spec expectation, Current implementation state, Reason, Temporary decision, Revisit condition, and Resolution.
Outcome checks:
- New spec and ADR templates must not contain
## Outcome.
- Existing imported spec or ADR documents may contain legacy
Outcome, but it must not be used as task status or to redefine product intent.
- If a spec or ADR contains
Outcome, report it as a structure issue when it contains task status, completion notes, or semantic changes that should be represented by replacement specs, ADRs, or deviations.
Non-semantic edit checks:
- Did the change modify existing spec documents?
- If yes, are those edits non-semantic?
- Do they preserve product behavior, domain contracts, scope, non-goals, constraints, verification rules, and accepted decisions?
- Were duplicated shared behaviors removed without changing feature-specific behavior?
- Were references to shared specs added in plain text without introducing new requirements?
- If a document was archived and replaced, was there a real semantic change that justified replacement?
- If there was only cleanup, was the document kept in place instead of archived?
Legacy migration check:
Flag files matching:
.worklog/**.specs/*.active.md.specs/*.retired.md.specs/archive/*.active.md.specs/archive/*.retired.md
These should be migrated to the Spec Guided Dev structure.
Output:
OK if the structure is fine.- Otherwise list concrete fixes.
- If a semantic change appears hidden as cleanup, report it in this form:
Potential semantic change hidden as cleanup:
- document: 0015.spec-search-options.md
- changed behavior: Esc handling changed from closing the dialog to ignoring Esc during validation
- suggested action: create a new spec document or ask the user
- If cleanup-only work is valid, report it in this form when useful:
Cleanup-only edit detected:
- document: 0010.spec-copy-conflict.md
- duplicated dialog behavior was replaced with a reference to 0027
- behavior appears preserved
- no replacement spec needed
- Do not modify files unless the user asks.
