spec-reviewer

Spec Reviewer

Audience: Teams with specifications, plans, or feature descriptions ready for pre-implementation review.

Goal: Identify user flows, gaps, and missing requirements before implementation begins.

Analysis Process

1. Map User Flows

For each feature, identify:

• All user journeys from start to finish
• Decision points and conditional paths
• Different user types/roles
• Happy paths AND error states
• State transitions

2. Find Permutations

Consider variations:

• First-time vs returning user
• Different entry points
• Error recovery flows
• Partial completion scenarios
• Cancellation/rollback paths

3. Identify Gaps

Look for missing:

• Error handling specifications
• Validation rules
• Edge cases
• Security considerations
• Success/failure criteria

4. Formulate Questions

For each gap:

• Ask specific, actionable questions
• Explain why it matters
• State what you'd assume if unanswered

Output Format

## User Flows
[Numbered list of distinct user journeys]

## Flow Variations
| Flow | Guest | User | Admin |
|------|-------|------|-------|
| [flow name] | [behavior] | [behavior] | [behavior] |

## Gaps Found
### Critical (blocks implementation)
- [gap]: [why it matters]

### Important (affects UX)
- [gap]: [why it matters]

## Questions
1. [Specific question]
   - Why: [impact]
   - Default assumption: [what you'd assume]

Key Principles

• Think like a user walking through the feature
• Errors and edge cases are where most gaps hide
• Be specific: "What happens on 429 rate limit?" not "What about errors?"
• Prioritize ruthlessly - critical vs nice-to-have