Smithery is now a part of Arcade.dev! Read more in our announcement here
Review user stories for quality, proper sizing, sequencing, and acceptance criteria. Use before converting to prd.json...
Review user stories for proper sizing, clear descriptions, dependency ordering, and comprehensive acceptance criteria before autonomous execution.
Output: Quality report with specific improvements for each story.
Good descriptions are:
Red flags:
Examples:
BAD (too long, multiple things):
As a user, I want to be able to create new tasks, edit existing tasks,
delete tasks, and also mark them as complete, with validation on all
fields and proper error handling so that I can manage my workflow.
GOOD (split into focused stories):
As a user, I want to create new tasks so that I can track my work.
Each story must be completable in ONE autonomous agent iteration. This is critical for Ralph/Claude Code loops.
Right-sized stories:
Too large (needs splitting):
Rule of thumb: If you can't describe the implementation in 2-3 sentences, split it.
Stories must be ordered so earlier stories don't depend on later ones.
Correct order:
Check for:
Good acceptance criteria are:
Every story must include:
- [ ] Typecheck passes
UI stories must also include:
- [ ] Verify in browser
Bad criteria (vague):
Good criteria (specific):
For each user story, check:
# Story Quality Review for [PRD Name]
## Summary
- Total stories: X
- Ready for implementation: X
- Needs revision: X
## Story-by-Story Review
### US-001: [Title]
**Status:** Ready | Needs Revision
**Description Review:**
- Length: OK (1 line) | TOO LONG (X lines)
- Format: Follows template | Missing [user/want/benefit]
- Focus: Single capability | Multiple capabilities (split)
**Scope Assessment:**
- Size: Appropriate | Too large (split into X stories)
- Complexity: One context window | Risk of overflow
**Dependency Check:**
- Dependencies: None | Depends on US-00X (OK, comes after) | ISSUE: Depends on US-00X (comes before!)
**Acceptance Criteria:**
- Verifiable: All | Issues with: [list vague criteria]
- Complete: Yes | Missing: [list missing scenarios]
- Includes typecheck: Yes | NO (add it!)
- Includes browser check: Yes | NO (add it!) | N/A (not UI)
**Recommended Changes:**
1. [Specific change]
2. [Specific change]
---
### US-002: [Title]
...
## Recommended Story Splits
### Original: US-003 "Build user dashboard"
**Problem:** Too large - involves schema, API, and multiple UI components
**Split into:**
1. US-003a: "Add dashboard_preferences table to database"
2. US-003b: "Create dashboard API endpoint"
3. US-003c: "Build dashboard layout component"
4. US-003d: "Add widget rendering to dashboard"
## Reordering Recommendations
Current order has dependency issues:
| Story | Current Position | Should Be | Reason |
|-------|------------------|-----------|--------|
| US-005 | 5 | 2 | Creates schema that US-003 needs |
| US-002 | 2 | 4 | Uses API from US-003 |
**Recommended order:** US-001, US-005, US-003, US-002, US-004
## Updated Acceptance Criteria
### US-001 (add these):
- [ ] Typecheck passes
- [ ] Loading state shown during API call
- [ ] Error state shown on failure
### US-004 (make specific):
- Before: "Handles errors properly"
- After: "Shows 'Failed to save. Try again.' on 500 error"
Fix: Split by layer (schema → backend → frontend) or by feature (list → create → edit → delete)
Fix: Ask "How would I verify this?" - if no clear answer, make it specific
Fix: Add criteria for: empty states, loading states, error states, edge cases
Fix: Map dependencies and reorder so each story only uses what exists
Fix: Always add "Typecheck passes" and "Verify in browser" for UI stories
