// Review user stories for quality, proper sizing, sequencing, and acceptance criteria. Use before converting to prd.json. Triggers on: review stories, check user stories, story quality, validate stories.
| name | story-quality |
| description | Review user stories for quality, proper sizing, sequencing, and acceptance criteria. Use before converting to prd.json. Triggers on: review stories, check user stories, story quality, validate stories. |
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
Convert bug reports into prd.json user stories for autonomous fixing. Use after running test-and-break skill. Triggers on: convert bugs to stories, fix these bugs, add bugs to prd, create fix stories.
Python-based threat modeling using pytm library for programmatic STRIDE analysis, data flow diagram generation, and automated security threat identification. Use when: (1) Creating threat models programmatically using Python code, (2) Generating data flow diagrams (DFDs) with automatic STRIDE threat identification, (3) Integrating threat modeling into CI/CD pipelines and shift-left security practices, (4) Analyzing system architecture for security threats across trust boundaries, (5) Producing threat reports with STRIDE categories and mitigation recommendations, (6) Maintaining threat models as code for version control and automation.
Hardcoded secret detection and prevention in git repositories and codebases using Gitleaks. Identifies passwords, API keys, tokens, and credentials through regex-based pattern matching and entropy analysis. Use when: (1) Scanning repositories for exposed secrets and credentials, (2) Implementing pre-commit hooks to prevent secret leakage, (3) Integrating secret detection into CI/CD pipelines, (4) Auditing codebases for compliance violations (PCI-DSS, SOC2, GDPR), (5) Establishing baseline secret detection and tracking new exposures, (6) Remediating historical secret exposures in git history.
Autonomous testing skill that opens a deployed app, goes through user flows, tries to break things, and writes detailed bug reports. Use after deploying to staging. Triggers on: test the app, find bugs, QA the deployment, break the app, test staging.
Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json.
Analyze a PRD for edge cases, failure modes, and scenarios that might be missed. Use after creating a PRD to strengthen it. Triggers on: analyze edge cases, find edge cases, what could go wrong, edge case analysis.
