Reviewing Specifications for Soundness

Overview

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.

When to Use

•After spec creation (before implementation)
•Before generating implementation plan
•When spec seems unclear or incomplete
•Periodically for important specs

Prerequisites

Ensure spec-kit is initialized:

{Skill: spec-kit}

If spec-kit prompts for restart, pause this workflow and resume after restart.

Spec Selection

If no spec is specified, discover available specs:

bash

# 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:

code

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:

code

No specs found in specs/ directory.

To create a spec first:
- Use `sdd:brainstorm` to refine ideas into a spec
- Use `/speckit.specify` to create a spec from clear requirements

Cannot review without a spec to review.

spec-kit Integration

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.

Review Dimensions

1. Completeness

•All sections filled
•No TBD or placeholder text
•All requirements defined
•Success criteria specified

2. Clarity

•No ambiguous language
•Concrete, specific requirements
•Edge cases explicitly defined
•Error handling specified

3. Implementability

•Can generate implementation plan
•Dependencies identified
•Constraints realistic
•Scope manageable

4. Testability

•Success criteria measurable
•Requirements verifiable
•Acceptance criteria clear

The Process

1. Load and Read Spec

Read the spec:

bash

cat specs/[feature-name]/spec.md

Read thoroughly, take notes on issues.

2. Check Structure

Required sections (should exist):

• Purpose/Overview
• Functional Requirements
• Success Criteria
• Error Handling

Recommended sections:

If sections missing:

•Note which ones
•Assess if truly needed for this spec
•Recommend additions

3. Review Completeness

For each section, check:

Purpose:

• Clearly states why feature exists
• Describes problem being solved
• Avoids implementation details

Functional Requirements:

• Numbered/listed clearly
• Each requirement is specific
• No "TBD" or placeholders
• All aspects covered

Success Criteria:

• Measurable outcomes defined
• Clear completion indicators
• Testable assertions

Error Handling:

• All error cases identified
• Handling approach specified
• Error messages/codes defined

Edge Cases:

• Boundary conditions listed
• Expected behavior specified
• Not marked as "TBD"

4. Check for Ambiguities

Red flag words/phrases:

•"should" (vs "must")
•"might", "could", "probably"
•"fast", "slow" (without metrics)
•"user-friendly" (vague)
•"handle appropriately" (non-specific)
•"etc." (incomplete list)
•"similar to..." (unclear)

For each ambiguity:

•Identify the vague requirement
•Note what's unclear
•Suggest specific alternative

5. Validate Implementability

Ask:

•Can I generate an implementation plan from this?
•Are file locations/components identifiable?
•Are dependencies clear?
•Is scope reasonable?

Check for:

•Unknown dependencies
•Unrealistic constraints
•Scope too large
•Conflicting requirements

6. Assess Testability

For each requirement:

•How will this be tested?
•Is the outcome verifiable?
•Can success be measured?

For success criteria:

•Are they specific enough to test?
•Can they be automated?
•Are they objective (not subjective)?

7. Check Against Constitution

If constitution exists (check both locations):

bash

if [ -f ".specify/memory/constitution.md" ]; then
  cat .specify/memory/constitution.md
elif [ -f "specs/constitution.md" ]; then
  cat specs/constitution.md
else
  echo "no-constitution"
fi

Validate:

•Does spec follow project principles?
•Are patterns consistent?
•Does error handling match standards?
•Are architectural decisions aligned?

Note any violations with reasoning.

8. Run Cross-Artifact Consistency Check (Optional)

If plan or tasks exist and /speckit.analyze is available:

Invoke /speckit.analyze to check consistency between:

•spec.md (requirements)
•plan.md (implementation approach)
•tasks.md (task list)

Report any mismatches or gaps found.

9. Generate Review Report

Report structure:

markdown

# Spec Review: [Feature Name]

**Spec:** specs/features/[feature].md
**Date:** YYYY-MM-DD
**Reviewer:** Claude (sdd: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]

10. Make Recommendation

If sound (minor issues only):

•✅ Ready for implementation
•Proceed with /speckit.implement

If needs work (important issues):

•⚠️ Fix issues before implementing
•Update spec, re-review

If major issues:

•❌ Not ready for implementation
•Significant rework needed
•May need re-brainstorming

Review Checklist

Use TodoWrite to track:

Example: Sound Spec

code

# 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`

Example: Needs Work

code

# 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

Quality Standards

A sound spec has:

•All sections complete
•No ambiguous language
•Specific, measurable requirements
•Identified dependencies
•Realistic constraints
•Clear error handling
•Defined edge cases
•Testable success criteria

A poor spec has:

•Missing sections
•Vague language
•Unmeasurable requirements
•Unknown dependencies
•Unrealistic constraints
•Unclear error handling
•Ignored edge cases
•Subjective criteria

Remember

Reviewing specs saves time in implementation.

•1 hour reviewing spec saves 10 hours debugging
•Ambiguities caught early prevent rework
•Complete specs enable smooth TDD
•Sound specs reduce spec/code drift

Be thorough but not pedantic:

•Flag real issues, not nitpicks
•Focus on what blocks implementation
•Suggest specific improvements
•Balance perfection with pragmatism

The goal is implementability, not perfection.