User Story Quality Review

Review user stories for proper sizing, clear descriptions, dependency ordering, and comprehensive acceptance criteria before autonomous execution.

The Job

Read the PRD with user stories
Evaluate each story against quality criteria
Identify issues and propose fixes
Ensure stories are ready for autonomous implementation

Output: Quality report with specific improvements for each story.

Quality Criteria

1. Story Description (1-2 Lines Max)

Good descriptions are:

Single sentence or two short sentences maximum
Written as "As a [user], I want [feature] so that [benefit]"
Focused on ONE capability
Clear about who benefits and why

Red flags:

Description longer than 2 lines
Multiple "and" conjunctions (doing too many things)
Vague benefit ("so that it works better")
Missing user perspective

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.

2. Story Scope (One Context Window)

Each story must be completable in ONE autonomous agent iteration. This is critical for Ralph/Claude Code loops.

Right-sized stories:

Add a database column/table
Create one UI component
Implement one API endpoint
Add one form with validation
Update one existing feature

Too large (needs splitting):

"Build the entire dashboard"
"Add authentication"
"Implement the checkout flow"
"Create the admin panel"

Rule of thumb: If you can't describe the implementation in 2-3 sentences, split it.

3. Dependency Ordering

Stories must be ordered so earlier stories don't depend on later ones.

Correct order:

Schema/database changes first
Backend logic/API endpoints second
UI components that use the backend third
Integration/polish features last

Check for:

UI story before the API it needs
Feature story before schema it requires
Delete/update before create exists

4. Acceptance Criteria Quality

Good acceptance criteria are:

Verifiable (can check if done)
Specific (not vague)
Complete (cover the full story)
Testable (can write a test for it)

Every story must include:

- [ ] Typecheck passes

UI stories must also include:

- [ ] Verify in browser

Bad criteria (vague):

"Works correctly"
"Good user experience"
"Handles errors properly"
"Is fast"

Good criteria (specific):

"Button disabled while request is pending"
"Error message shown below input field"
"Response time < 200ms for 1000 items"
"Empty state shows 'No items yet' message"

Review Checklist

For each user story, check:

Description Quality

1-2 lines maximum
Follows "As a... I want... so that..." format
Single focused capability
Clear user and benefit

Scope Assessment

Can be implemented in one session
Describable in 2-3 implementation sentences
No "and also" or multiple features
Doesn't require multiple file types of changes

Dependency Check

Doesn't depend on later stories
Database changes come before code that uses them
API exists before UI that calls it

Acceptance Criteria

Output Format

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

Common Issues and Fixes

Issue: Story too large

Fix: Split by layer (schema → backend → frontend) or by feature (list → create → edit → delete)

Issue: Vague acceptance criteria

Fix: Ask "How would I verify this?" - if no clear answer, make it specific

Issue: Missing error handling

Fix: Add criteria for: empty states, loading states, error states, edge cases

Issue: Wrong order

Fix: Map dependencies and reorder so each story only uses what exists

Issue: Missing typecheck/browser verification

Fix: Always add "Typecheck passes" and "Verify in browser" for UI stories

Tips

Be ruthless about scope: Smaller stories are always better for autonomous execution
Think in iterations: Each story = one Ralph/Claude iteration
Verify means verify: If you can't write a test for it, it's not verifiable
Order matters: Wrong order = broken builds and wasted iterations

story-quality