spec-review

When this skill applies

This skill is invoked when:

• •The user explicitly calls /spec-review
• •The user asks to review, validate, or check a spec
• •The user asks if a spec is "ready" or "complete"

Important: If a spec file contains a reference to /spec-refine, treat user questions about spec quality or completeness as review requests.

What to do when this skill is invoked

When the user invokes /spec-review, automatically detect the spec file to review:

1. •Check IDE context first - Look for ide_opened_file or ide_selection tags in the context. If the user has a .md file from .claude/specs/ open, use that file.
2. •Check conversation context - If a spec file path was mentioned recently in the conversation, use that.
3. •Check arguments - If the user provided a path or feature name (e.g., /spec-review auth), search .claude/specs/ for a matching file.
4. •Only ask if ambiguous - If multiple specs could match or none is found, ask the user which spec to review.

Your job is to:

1. •Locate the spec file - Use the detection logic above to find the spec
2. •Read and analyze the spec - Understand the full feature description
3. •Validate completeness - Check that all sections are filled in (not placeholders)
4. •Review for ambiguities - Identify vague, unclear, or contradictory statements
5. •Verify acceptance criteria - Ensure criteria are testable, specific, and follow BDD format
6. •Check technical feasibility - Review the technical design against the codebase patterns
7. •Identify gaps - Highlight missing dependencies, edge cases, or unaddressed risks
8. •Report findings - Document issues and suggest improvements in a single summary

Review checklist

• • All sections are filled in (not placeholder text)
• • Problem statement clearly identifies the issue and affected users
• • Proposed solution is high-level and implementation-agnostic
• • Acceptance criteria are testable and specific (BDD format: "Given X, When Y, Then Z")
• • Technical design references real codebase files and patterns
• • Dependencies and risks are realistically assessed
• • Out of scope items prevent scope creep
• • Implementation steps are discrete, reviewable, and logically ordered
• • No contradictions between sections
• • All assumptions are explicitly stated

Process

1. •Read and deeply analyze the spec document
2. •Check each section against the checklist above
3. •Cross-reference the spec against the actual codebase where possible
4. •Update the spec file with a Review Findings section containing:
   • •Overall assessment (Ready for implementation / Needs refinement)
   • •Issues found (organized by section)
   • •Specific suggestions for improvement
   • •Questions that need answers (formatted as checkboxes)
5. •If the spec already has a Review Findings section, update it with fresh findings
6. •Remove the Review Findings section if no issues remain (spec is ready)

Review Findings Format

Add or update a section at the end of the spec file:

---

## Review Findings

**Status:** ⚠️ Needs refinement | ✅ Ready for implementation

### Issues

- [ ] **[Section Name]**: Description of issue
- [ ] **[Section Name]**: Another issue

### Questions

- [ ] Question that needs to be answered?
- [ ] Another question?

### Suggestions

- Suggestion for improvement
- Another suggestion

---
*Run `/spec-review` again after addressing the items above.*

The user can:

1. •Check off items as they address them
2. •Edit the spec directly to fix issues
3. •Answer questions inline
4. •Run /spec-review again to get updated findings

Key points

• •Be thorough but not pedantic - focus on clarity and feasibility
• •Write findings directly to the spec file - this enables iterative review
• •Use checkbox format for issues and questions so users can track progress
• •Remove the Review Findings section entirely when the spec passes review
• •Output a brief summary to the user after updating the file
• •Suggest using /spec-refine if significant restructuring is needed
• •Suggest using /spec-implement once the spec is approved (no Review Findings section)