Reviews spec.md files for completeness, clarity, implementability, testability, and structure. Identifies ambiguities, gaps, and missing sections before implementation.
From spexnpx claudepluginhub rhuss/cc-spex --plugin spexThis skill uses the workspace's default tool permissions.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Guides implementation of event-driven hooks in Claude Code plugins using prompt-based validation and bash commands for PreToolUse, Stop, and session events.
Validate specification quality before implementation begins.
A poor spec leads to confusion, rework, and spec/code drift. A sound spec enables smooth implementation.
This skill checks: completeness, clarity, implementability, and testability.
Ensure spec-kit is initialized:
{Skill: spec-kit}
If spec-kit prompts for restart, pause this workflow and resume after restart.
If no spec is specified, discover available specs:
# List all specs in the project
fd -t f "spec.md" specs/ 2>/dev/null | head -20
If specs found: Present list and ask user to select one using AskUserQuestion.
Example:
Found 2 specs in this project:
1. specs/0001-user-auth/spec.md
2. specs/0002-api-gateway/spec.md
Which spec would you like to review?
If no specs found: Inform user:
No specs found in specs/ directory.
To create a spec first:
- Use `spex:brainstorm` to refine ideas into a spec
- Use `/speckit-specify` to create a spec from clear requirements
Cannot review without a spec to review.
This skill can use /speckit-* slash commands when available:
/speckit-clarify - Find underspecified areas in the spec/speckit-analyze - Cross-artifact consistency check (if plan/tasks exist)If /speckit-* commands are available:
Use them to assist with review, but always perform manual review as well.
If /speckit-* commands are not available:
Proceed with manual review only. This is acceptable.
Read the spec:
cat specs/[feature-name]/spec.md
Read thoroughly, take notes on issues.
Required sections (should exist):
Recommended sections:
If sections missing:
For each section, check:
Purpose:
Functional Requirements:
Success Criteria:
Error Handling:
Edge Cases:
Red flag words/phrases:
For each ambiguity:
Ask:
Check for:
For each requirement:
For success criteria:
If constitution exists:
if [ -f ".specify/memory/constitution.md" ]; then
cat .specify/memory/constitution.md
else
echo "no-constitution"
fi
Validate:
Note any violations with reasoning.
If plan or tasks exist and /speckit-analyze is available:
Invoke /speckit-analyze to check consistency between:
Report any mismatches or gaps found.
Report structure:
# Spec Review: [Feature Name]
**Spec:** specs/features/[feature].md
**Date:** YYYY-MM-DD
**Reviewer:** Claude (spex:review-spec)
## Overall Assessment
**Status:** ✅ SOUND / ⚠️ NEEDS WORK / ❌ MAJOR ISSUES
**Summary:** [1-2 sentence overall assessment]
## Completeness: [Score/5]
### Structure
- [✓/✗] All required sections present
- [✓/✗] Recommended sections included
- [✓/✗] No placeholder text
### Coverage
- [✓/✗] All functional requirements defined
- [✓/✗] Error cases identified
- [✓/✗] Edge cases covered
- [✓/✗] Success criteria specified
**Issues:**
- [List any completeness issues]
## Clarity: [Score/5]
### Language Quality
- [✓/✗] No ambiguous language
- [✓/✗] Requirements are specific
- [✓/✗] No vague terms
**Ambiguities Found:**
1. [Quote ambiguous text]
- Issue: [What's unclear]
- Suggestion: [Specific alternative]
## Implementability: [Score/5]
### Plan Generation
- [✓/✗] Can generate implementation plan
- [✓/✗] Dependencies identified
- [✓/✗] Constraints realistic
- [✓/✗] Scope manageable
**Issues:**
- [List any implementability issues]
## Testability: [Score/5]
### Verification
- [✓/✗] Success criteria measurable
- [✓/✗] Requirements verifiable
- [✓/✗] Acceptance criteria clear
**Issues:**
- [List any testability issues]
## Constitution Alignment
[If constitution exists]
- [✓/✗] Follows project principles
- [✓/✗] Patterns consistent
- [✓/✗] Error handling aligned
**Violations:**
- [List any violations]
## Recommendations
### Critical (Must Fix Before Implementation)
- [ ] [Critical issue 1]
- [ ] [Critical issue 2]
### Important (Should Fix)
- [ ] [Important issue 1]
### Optional (Nice to Have)
- [ ] [Optional improvement 1]
## Conclusion
[Final assessment and recommendation]
**Ready for implementation:** Yes / No / After fixes
**Next steps:**
[What should be done]
If sound (minor issues only):
/speckit-implementIf needs work (important issues):
If major issues:
Use TodoWrite to track:
/speckit-analyze for cross-artifact consistency (if available)# Spec Review: User Profile Update API
**Spec:** specs/features/user-profile-api.md
**Status:** ✅ SOUND
## Overall Assessment
Specification is well-written, complete, and ready for implementation.
Minor suggestions for improvement but no blocking issues.
## Completeness: 5/5
✓ All required sections present
✓ All functional requirements clearly defined (6 requirements)
✓ All error cases identified (4 cases)
✓ All edge cases covered (3 cases)
✓ Success criteria specified and measurable
## Clarity: 4.5/5
✓ Requirements are specific and unambiguous
✓ Error handling clearly defined
⚠️ One minor ambiguity (see below)
**Ambiguities Found:**
1. "Response should be fast"
- Issue: "Fast" is subjective
- Suggestion: Specify "Response time < 200ms" or remove
## Implementability: 5/5
✓ Can generate detailed implementation plan
✓ All dependencies identified (JWT auth, database)
✓ Constraints are realistic
✓ Scope is manageable (single endpoint)
## Testability: 5/5
✓ All success criteria measurable
✓ Each requirement verifiable through tests
✓ Clear acceptance criteria
## Constitution Alignment
✓ Follows RESTful conventions (from constitution)
✓ Error handling matches project patterns
✓ Auth requirements aligned with standards
## Recommendations
### Important (Should Fix)
- [ ] Clarify "fast" response requirement (specify < 200ms or remove)
### Optional
- [ ] Consider adding rate limiting requirement
- [ ] Specify audit logging if required by project
## Conclusion
Excellent spec, ready for implementation after minor clarification on
performance requirement.
**Ready for implementation:** Yes (after performance clarification)
**Next steps:** Clarify "fast" requirement, then proceed to `/speckit-implement`
# Spec Review: Real-time Notifications
**Spec:** specs/features/real-time-notifications.md
**Status:** ⚠️ NEEDS WORK
## Overall Assessment
Specification has good foundation but several important gaps that will
cause confusion during implementation.
## Completeness: 3/5
✓ Purpose clearly stated
✗ Non-functional requirements missing
✗ Error handling incomplete
⚠️ Edge cases partially defined
**Issues:**
- No specification of real-time latency requirements
- Database storage requirements unclear
- Error recovery not defined
- Scalability requirements missing
## Clarity: 3/5
**Ambiguities Found:**
1. "Notifications should appear in real-time"
- Issue: "Real-time" undefined (< 100ms? < 1s? < 5s?)
- Suggestion: Specify exact latency requirement
2. "Handle notification delivery failures appropriately"
- Issue: "Appropriately" is non-specific
- Suggestion: Define retry logic, fallback, user notification
3. "Support many users"
- Issue: "Many" is vague
- Suggestion: Specify target (100? 1000? 10000?)
## Implementability: 2/5
✗ Cannot generate complete implementation plan
✗ Technology stack not specified (WebSocket? SSE? Polling?)
✗ Storage mechanism unclear
**Issues:**
- Is this WebSocket or polling? Spec doesn't say
- Where are notifications stored? For how long?
- What happens when user offline?
- No mention of infrastructure requirements
## Testability: 3/5
⚠️ Some criteria measurable, others vague
**Issues:**
- "Users receive notifications quickly" - not measurable
- "System handles failures" - no specific test criteria
## Recommendations
### Critical (Must Fix Before Implementation)
- [ ] Define exact real-time latency requirement (< Xms)
- [ ] Specify technology (WebSocket vs polling vs SSE)
- [ ] Define notification storage (where, how long)
- [ ] Specify error handling and retry logic
- [ ] Define scalability target (number of users)
### Important (Should Fix)
- [ ] Add detailed error cases
- [ ] Specify offline handling
- [ ] Define notification expiration
- [ ] Add infrastructure requirements
## Conclusion
Spec has good intent but lacks critical technical details needed for
implementation. Requires significant expansion before coding can begin.
**Ready for implementation:** No
**Next steps:**
1. Address all critical issues
2. Re-review spec
3. Then proceed to implementation
A sound spec has:
A poor spec has:
Reviewing specs saves time in implementation.
Be thorough but not pedantic:
The goal is implementability, not perfection.