ousiass spec-review-en
Review specification documents created by spec-gen, present findings one by one, and fix with user approval.
Prerequisites
- Claude Code environment
- spec-gen format specs in docs/ or spec/ directory
Arguments
- No args: auto-detect and review specs
- Path: review specs in specified directory
- Mode:
consistencycode-driftqualityall
Review Modes
| Mode | Description |
|---|---|
| Consistency | Cross-reference contradictions between spec documents |
| Code drift | Detect gaps between implementation code and specs, update specs |
| Quality | Format issues, ambiguous descriptions, missing diagrams, stale revision history |
| All | Run all 3 modes sequentially |
Phase 1: Detect and Load Specs
1-1: Discover specs
If path argument provided:
- Read files/directory at that path directly
If no argument: Search with Glob:
**/spec/**/*.md
**/specs/**/*.md
**/docs/**/*.md
**/specifications/**/*.md
**/design/**/*.md
If nothing found, ask user for path.
1-2: Read all specs
Read all discovered specs to understand current state.
1-3: Mode selection
If mode not specified in arguments, ask with AskUserQuestion:
Question: Which review mode?
Choices:
1. Consistency — cross-reference contradictions between spec documents
2. Code drift — detect gaps between code and specs, update specs
3. Quality — format, ambiguous text, missing diagrams, revision history
4. All — run all 3 modes sequentially
Phase 2: Review
Run review for selected mode(s). For "All": consistency → code drift → quality.
Consistency checks
| Cross-reference | Check |
|---|---|
| Requirements ↔ API spec | Each feature has corresponding endpoints |
| Requirements ↔ Component design | Each screen has corresponding components |
| ER diagram ↔ API spec | Request/response matches table definitions |
| ER diagram ↔ Requirements | Data used by features is defined as tables |
| Architecture ↔ Non-functional requirements | Tech choices satisfy non-functional requirements |
| Components ↔ API spec | APIs needed by components are defined |
Code drift checks
Explore implementation code and verify:
| Cross-reference | Check |
|---|---|
| API spec ↔ Routes/handlers | Endpoint paths, methods, parameters match |
| ER diagram ↔ Migrations/models | Table names, columns, types, constraints match |
| Component design ↔ Implementation | Component names, props, dependencies match |
| Architecture ↔ Directory structure | Layer structure, tech choices match reality |
Skip if no code exists, report accordingly.
Quality checks
| Target | Check |
|---|---|
| Mermaid diagrams | Required diagrams present, no syntax errors |
| Revision history | All docs have revision history section with valid dates |
| Ambiguous wording | Vague terms like "as needed", "etc.", "appropriate" |
| Table format | Markdown table formatting is correct |
| Section structure | Heading level consistency, required sections present |
| Link integrity | Cross-references between documents are not broken |
Phase 3: Present Findings and Fix
Present each finding one at a time via AskUserQuestion.
Finding format
Question: [Mode] Finding N/M — [filename]
[Description of the issue]
[Quoted excerpt if applicable]
[Proposed fix summary]
Choices:
1. Fix — apply proposed fix
2. Modify fix — specify different fix approach before applying
3. Skip — do not address this finding
4. Fix all remaining — apply all remaining fixes without confirmation
5. End review — discard remaining findings and finish
Applying fixes
- "Fix": Apply fix with Edit
- "Modify fix": Ask for approach via AskUserQuestion with freeText, then apply
- "Fix all remaining": Apply all subsequent fixes without confirmation
- Update revision history on each modified document (increment version, add change description and reason)
Phase 4: Completion
- Display fix summary:
- Finding count per mode
- Breakdown: fixed / skipped / modified
- List of modified files
- Ask via
AskUserQuestionwhether to commit - If committing, follow CLAUDE.md conventions
Rules
- Always use
AskUserQuestionwith choices for questions. Never ask via plain text - Use
allowFreeText: truewhen free-form input is needed - Order findings by severity (high → low)
- Group findings by file (present same-file findings consecutively)
- Edit existing files only. Do not create new files
- Use execution date for revision history dates
- Track progress with TaskCreate/TaskUpdate