review-draft-story
Comprehensive draft story review with parallel specialist sub-agents. Spawns PM, UX, and SM agents to review stories from product, design, and implementation readiness perspectives before development begins.
When & Why to Use This Skill
The 'review-draft-story' skill is a sophisticated Agile assistant designed to perform multi-dimensional audits of user stories before development begins. By orchestrating parallel specialist sub-agents—simulating Product Manager, UX Designer, and Scrum Master roles—it identifies gaps in requirements, design specifications, and technical readiness. This proactive review process ensures that stories meet the 'Definition of Ready,' significantly reducing rework, scope creep, and implementation delays in the software development lifecycle.
Use Cases
- Agile Sprint Grooming: Automatically audit draft stories to ensure they are complete, testable, and provide clear business value before being committed to a sprint.
- UX & Design Validation: Use the specialized UX sub-agent to verify that user flows, interaction states, and accessibility requirements are fully documented for frontend tasks.
- Technical Readiness Assessment: Identify missing technical documentation, architectural dependencies, or environment variables before developers start coding to prevent mid-sprint blockers.
- Post-Implementation PR Review: Re-run the review with the '--pr' flag to verify that the final code implementation aligns with the original story's acceptance criteria and quality standards.
| name | review-draft-story |
|---|---|
| description | Comprehensive draft story review with parallel specialist sub-agents. Spawns PM, UX, and SM agents to review stories from product, design, and implementation readiness perspectives before development begins. |
/review-draft-story - Draft Story Review
Description
Full-spectrum story review using parallel specialist sub-agents BEFORE implementation begins. Each specialist reviews from their domain perspective, findings are aggregated, and a final readiness decision is produced.
Key Features:
- Parallel specialist sub-agents (PM, UX, SM/Checklist)
- Product requirements completeness validation
- UX/UI specification review
- Implementation readiness assessment
- Consolidated feedback and recommendations
- GO/NO-GO decision with actionable fixes
Usage
# Review a specific story
/review-draft-story 2002
# Review a story by file path
/review-draft-story docs/stories/epic-6-wishlist/wish-2002-add-item-flow.md
# Quick review (skip deep analysis)
/review-draft-story 2002 --quick
# Focus on specific aspect
/review-draft-story 2002 --focus=ux
# Skip PM review (no product context available)
/review-draft-story 2002 --skip-pm
Parameters
- story - Story number (e.g.,
2002) or full path to story file - --quick - Run lightweight review, skip deep specialists
- --focus - Focus on specific aspect:
pm,ux, orsm - --skip-pm - Skip PM review if no PRD/epic context
- --skip-ux - Skip UX review if no UI in this story
EXECUTION INSTRUCTIONS
CRITICAL: Use Task tool to spawn parallel sub-agents. Use TodoWrite to track progress.
Phase 0: Initialize & Gather Context
TodoWrite([
{ content: "Gather story context", status: "in_progress", activeForm: "Gathering context" },
{ content: "Spawn specialist sub-agents", status: "pending", activeForm: "Spawning specialists" },
{ content: "Collect specialist feedback", status: "pending", activeForm: "Collecting feedback" },
{ content: "Aggregate findings", status: "pending", activeForm: "Aggregating findings" },
{ content: "Generate review report", status: "pending", activeForm: "Generating report" }
])
Gather context:
- Load
.bmad-core/core-config.yamlfor story locations and patterns - Locate and read the story file:
- If number provided: Search in
docs/stories/for matching file - If path provided: Read directly
- If number provided: Search in
- Extract from story:
- Title and description
- Acceptance criteria
- Tasks/subtasks
- Dev Notes section
- Testing section
- Referenced files/architecture
- Load parent epic if referenced
- Load architecture docs if referenced in story
- Determine if story has UI components (affects UX review)
Skip Logic:
- Skip UX review if story has no UI components (API-only, backend, migrations)
- Skip PM review if
--skip-pmor no epic/PRD context available
Phase 1: Spawn Specialist Sub-Agents
CRITICAL: Spawn all applicable specialists in parallel using run_in_background: true
1.1 Product Manager (PM) Specialist
Task(
subagent_type: "general-purpose",
model: "haiku",
description: "PM story review",
run_in_background: true,
prompt: "You are John, an experienced Product Manager reviewing a story draft.
Story file path: {STORY_FILE_PATH}
Epic context: {EPIC_CONTENT or 'Not provided'}
Review the story from a PRODUCT perspective:
1. **Requirements Clarity**
- Are requirements clearly defined and unambiguous?
- Is the 'why' (business value) clearly articulated?
- Are success metrics or outcomes defined?
2. **Scope Appropriateness**
- Is the scope right-sized for a single story?
- Are there scope creep risks?
- Should this be split into multiple stories?
3. **User Value**
- Is user value clearly identified?
- Does the story solve a real user problem?
- Is the user persona/context clear?
4. **Acceptance Criteria Quality**
- Are ACs testable and measurable?
- Do ACs cover happy path AND edge cases?
- Are ACs written from user perspective (not technical)?
5. **Dependencies & Sequencing**
- Are dependencies clearly identified?
- Is this story properly sequenced in the epic?
- Are there hidden dependencies?
6. **Risk Identification**
- Are potential risks called out?
- Are there business/compliance considerations?
- Is there fallback behavior defined?
Output format:
```yaml
pm_review:
overall_assessment: READY|NEEDS_WORK|BLOCKED
confidence: high|medium|low
requirements_clarity:
status: PASS|PARTIAL|FAIL
issues:
- issue: 'Description'
severity: low|medium|high
suggestion: 'How to fix'
scope_appropriateness:
status: PASS|PARTIAL|FAIL
issues: []
user_value:
status: PASS|PARTIAL|FAIL
issues: []
acceptance_criteria:
status: PASS|PARTIAL|FAIL
issues: []
dependencies:
status: PASS|PARTIAL|FAIL
issues: []
risks:
status: PASS|PARTIAL|FAIL
issues: []
top_recommendations:
- 'Most important fix or improvement'
- 'Second priority'
```"
)
1.2 UX Expert Specialist
Task(
subagent_type: "general-purpose",
model: "haiku",
description: "UX story review",
run_in_background: true,
prompt: "You are Sally, an experienced UX Expert reviewing a story draft.
Story file path: {STORY_FILE_PATH}
Architecture context: {ARCHITECTURE_CONTENT or 'Not provided'}
Review the story from a UX/UI perspective:
1. **User Flow Clarity**
- Is the user journey clearly described?
- Are entry/exit points defined?
- Is the happy path obvious?
2. **Interaction Design**
- Are user interactions specified?
- Are click/tap targets and gestures defined?
- Is feedback for user actions specified?
3. **Visual Specifications**
- Are layout requirements clear?
- Is component placement described?
- Are spacing/sizing considerations mentioned?
4. **State Handling**
- Are loading states defined?
- Are error states and messages specified?
- Are empty states considered?
- Is disabled state behavior clear?
5. **Accessibility Considerations**
- Are a11y requirements mentioned?
- Is keyboard navigation considered?
- Are screen reader needs addressed?
6. **Responsive Design**
- Are mobile/tablet considerations mentioned?
- Are breakpoint behaviors defined?
- Is touch vs mouse interaction considered?
7. **Component Reusability**
- Can existing components be reused?
- Are new components clearly specified?
- Is design system alignment mentioned?
Output format:
```yaml
ux_review:
overall_assessment: READY|NEEDS_WORK|BLOCKED
confidence: high|medium|low
ui_complexity: low|medium|high
user_flow:
status: PASS|PARTIAL|FAIL
issues:
- issue: 'Description'
severity: low|medium|high
suggestion: 'How to fix'
interaction_design:
status: PASS|PARTIAL|FAIL
issues: []
visual_specs:
status: PASS|PARTIAL|FAIL
issues: []
state_handling:
status: PASS|PARTIAL|FAIL
issues: []
accessibility:
status: PASS|PARTIAL|FAIL
issues: []
responsive:
status: PASS|PARTIAL|FAIL
issues: []
component_reuse:
status: PASS|PARTIAL|FAIL
issues: []
top_recommendations:
- 'Most important UX improvement'
- 'Second priority'
suggested_wireframe_notes: |
Brief description of key UI elements needed
```"
)
1.3 Scrum Master / Implementation Readiness Specialist
This sub-agent executes the formal Story Draft Checklist (.bmad-core/checklists/story-draft-checklist.md)
Task(
subagent_type: "general-purpose",
model: "haiku",
description: "SM checklist review",
run_in_background: true,
prompt: "You are Bob, a Scrum Master executing the Story Draft Checklist.
Story file path: {STORY_FILE_PATH}
Checklist path: .bmad-core/checklists/story-draft-checklist.md
IMPORTANT: Read both the story file AND the checklist file. Execute each
checklist item systematically.
Execute each section of the Story Draft Checklist:
## 1. GOAL & CONTEXT CLARITY
Evaluate each checkbox:
- [ ] Story goal/purpose is clearly stated
- [ ] Relationship to epic goals is evident
- [ ] How the story fits into overall system flow is explained
- [ ] Dependencies on previous stories are identified (if applicable)
- [ ] Business context and value are clear
## 2. TECHNICAL IMPLEMENTATION GUIDANCE
Evaluate each checkbox:
- [ ] Key files to create/modify are identified (not necessarily exhaustive)
- [ ] Technologies specifically needed for this story are mentioned
- [ ] Critical APIs or interfaces are sufficiently described
- [ ] Necessary data models or structures are referenced
- [ ] Required environment variables are listed (if applicable)
- [ ] Any exceptions to standard coding patterns are noted
## 3. REFERENCE EFFECTIVENESS
Evaluate each checkbox:
- [ ] References to external documents point to specific relevant sections
- [ ] Critical information from previous stories is summarized (not just referenced)
- [ ] Context is provided for why references are relevant
- [ ] References use consistent format (e.g., docs/filename.md#section)
## 4. SELF-CONTAINMENT ASSESSMENT
Evaluate each checkbox:
- [ ] Core information needed is included (not overly reliant on external docs)
- [ ] Implicit assumptions are made explicit
- [ ] Domain-specific terms or concepts are explained
- [ ] Edge cases or error scenarios are addressed
## 5. TESTING GUIDANCE
Evaluate each checkbox:
- [ ] Required testing approach is outlined
- [ ] Key test scenarios are identified
- [ ] Success criteria are defined
- [ ] Special testing considerations are noted (if applicable)
For each checkbox, mark: [x] PASS, [~] PARTIAL, [ ] FAIL
Output format:
```yaml
sm_review:
overall_assessment: READY|NEEDS_REVISION|BLOCKED
clarity_score: 1-10
checklist_results:
goal_context_clarity:
status: PASS|PARTIAL|FAIL
items:
- item: 'Story goal/purpose is clearly stated'
status: PASS|PARTIAL|FAIL
note: 'Optional note if issue found'
issues: []
technical_guidance:
status: PASS|PARTIAL|FAIL
items:
- item: 'Key files to create/modify are identified'
status: PASS|PARTIAL|FAIL
note: ''
issues: []
reference_effectiveness:
status: PASS|PARTIAL|FAIL
items: []
issues: []
self_containment:
status: PASS|PARTIAL|FAIL
items: []
issues: []
testing_guidance:
status: PASS|PARTIAL|FAIL
items: []
issues: []
validation_table:
- category: '1. Goal & Context Clarity'
status: PASS|PARTIAL|FAIL
issues: 'Brief description or empty'
- category: '2. Technical Implementation Guidance'
status: PASS|PARTIAL|FAIL
issues: ''
- category: '3. Reference Effectiveness'
status: PASS|PARTIAL|FAIL
issues: ''
- category: '4. Self-Containment Assessment'
status: PASS|PARTIAL|FAIL
issues: ''
- category: '5. Testing Guidance'
status: PASS|PARTIAL|FAIL
issues: ''
developer_perspective:
could_implement: true|false
questions:
- 'Question a dev would have'
delay_risks:
- 'What might cause rework'
blocking_issues:
- 'Critical issue that blocks implementation'
should_fix_issues:
- 'Important but not blocking'
top_recommendations:
- 'Most important fix'
- 'Second priority'
```"
)
Phase 2: Collect Results
Wait for all specialists to complete:
results = {
pm: TaskOutput(task_id: "{pm_id}", block: true),
ux: TaskOutput(task_id: "{ux_id}", block: true),
sm: TaskOutput(task_id: "{sm_id}", block: true)
}
Phase 3: Synthesize Concerns
Parent QA agent extracts and synthesizes all sub-agent findings into a unified concerns list:
concerns:
- id: 1
source: pm|ux|sm
severity: blocking|should_fix|note
category: requirements|scope|ux|technical|testing|etc
concern: "Clear description of the issue"
suggestion: "How to address it"
Severity Levels:
- blocking: Must fix before story can proceed
- should_fix: Important issue that should be addressed
- note: Minor observation, nice-to-have improvement
Synthesis Rules:
- Parse YAML output from each sub-agent
- Extract all issues with severity >= should_fix as concerns
- Deduplicate similar concerns (keep highest severity)
- Assign sequential IDs
- Sort by severity (blocking → should_fix → note)
Phase 4: Decision & Action
Decision Logic:
blocking_count = len([c for c in concerns if c.severity == 'blocking'])
should_fix_count = len([c for c in concerns if c.severity == 'should_fix'])
if blocking_count > 0:
decision = 'FAIL'
action = 'APPEND_CONCERNS_TO_STORY'
elif should_fix_count > 0:
decision = 'CONCERNS'
action = 'APPEND_CONCERNS_TO_STORY'
else:
decision = 'PASS'
action = 'APPROVE_STORY' # or MERGE_PR if post-implementation
Path A: FAIL or CONCERNS → Append to Story
Append concerns section to story file:
## Review Concerns
> **Review Date:** {ISO-8601}
> **Reviewed By:** PM (John), UX (Sally), SM (Bob)
> **Decision:** {FAIL|CONCERNS}
### Blocking Issues
- **[1] PM - requirements:** User value not clearly articulated
- *Suggestion:* Add explicit user benefit statement to story description
- **[2] SM - testing:** No test scenarios defined for error cases
- *Suggestion:* Add error handling test cases to Testing section
### Should-Fix Issues
- **[3] UX - states:** Loading state not specified
- *Suggestion:* Define skeleton/spinner behavior during data fetch
### Notes
- **[4] PM - scope:** Consider splitting into two stories if complexity grows
---
Update story status:
# In story frontmatter or status field:
status: Draft → Needs Revision # if FAIL
status: Draft → Conditional # if CONCERNS (can proceed with awareness)
Path B: PASS (No Concerns) → Auto-Approve/Merge
When all sub-agents return zero blocking or should_fix concerns:
For Draft Story Review (pre-implementation):
Update story status to Approved:
status: Draft → ApprovedAdd approval stamp to story:
## Review Approval > **Review Date:** {ISO-8601} > **Reviewed By:** PM (John), UX (Sally), SM (Bob) > **Decision:** APPROVED All review criteria passed. Story is ready for implementation. ---Report success and next step:
✓ APPROVED - Ready for /implement {story_id}
For PR Review (post-implementation):
Merge the PR:
gh pr merge {PR_NUMBER} --squash --delete-branchUpdate story status to Done:
status: In Review → DoneArchive the story:
mv docs/stories/{epic}/{story}.md docs/_archive/completed-stories/Close associated GitHub issue (if any):
gh issue close {ISSUE_NUMBER} --comment "Completed and merged in PR #{PR_NUMBER}"
Phase 5: Report to User
════════════════════════════════════════════════════════════════════
Story Review: {STORY_ID} - {STORY_TITLE}
════════════════════════════════════════════════════════════════════
SPECIALIST RESULTS
──────────────────────────────────────────────────────────────────────
PM (John): {PASS|CONCERNS} - {1-line summary}
UX (Sally): {PASS|CONCERNS|SKIPPED} - {1-line summary}
SM (Bob): {PASS|CONCERNS} - {1-line summary}
──────────────────────────────────────────────────────────────────────
DECISION: {PASS|CONCERNS|FAIL}
CONCERNS: {N} total ({blocking} blocking, {should_fix} should-fix)
──────────────────────────────────────────────────────────────────────
{If concerns > 0:}
CONCERNS LIST
1. [{severity}] {source}: {concern}
→ {suggestion}
2. ...
ACTION TAKEN
{If PASS - draft:} Story approved. Status: Draft → Approved
{If PASS - PR:} PR #{N} merged. Story archived. Status: Done
{If CONCERNS/FAIL:} Concerns appended to story. Status: Needs Revision
NEXT STEPS
{If PASS:} → /implement {story_id}
{If CONCERNS/FAIL:} → Address concerns, then re-run /review-draft-story
════════════════════════════════════════════════════════════════════
Sub-Agent Architecture
Main Orchestrator (/review-draft-story)
│
├─▶ Phase 0: Context Gathering (inline)
│ ├── Load story file
│ ├── Load epic context (if available)
│ ├── Detect if PR exists (post-impl review)
│ └── Determine applicable reviews (skip UX for API-only, etc.)
│
├─▶ Phase 1: Specialist Sub-Agents (parallel, haiku, run_in_background)
│ ├── PM (John) - product/requirements perspective
│ ├── UX (Sally) - design/interaction perspective
│ └── SM (Bob) - checklist execution
│
├─▶ Phase 2: Collect Results (blocking wait for all)
│
├─▶ Phase 3: Synthesize Concerns (inline)
│ ├── Parse each sub-agent's YAML output
│ ├── Extract issues as concerns
│ ├── Deduplicate and sort by severity
│ └── Build unified concerns list
│
├─▶ Phase 4: Decision & Action (inline)
│ ├── IF no concerns → PASS → approve/merge
│ └── IF concerns → FAIL/CONCERNS → append to story
│
└─▶ Phase 5: Report (inline)
Concern Categories
| Source | Categories |
|---|---|
| PM | requirements, scope, user_value, acceptance_criteria, dependencies, risks |
| UX | user_flow, interaction, visual, states, accessibility, responsive, components |
| SM | goal_clarity, technical_guidance, references, self_containment, testing, tasks |
Usage Modes
Draft Story Review (pre-implementation)
/review-draft-story 2002
- Reviews story before coding begins
- PASS → status becomes "Approved", ready for
/implement - CONCERNS/FAIL → concerns appended, status becomes "Needs Revision"
PR Review (post-implementation)
/review-draft-story 2002 --pr
- Reviews story after implementation, with associated PR
- PASS → PR merged, story archived, status becomes "Done"
- CONCERNS/FAIL → concerns appended, PR remains open
Quick Review
/review-draft-story 2002 --quick
- Lightweight review, skips deep analysis
- Good for simple stories or re-reviews after fixes
Skip Specific Reviewers
/review-draft-story 2002 --skip-ux # API-only story
/review-draft-story 2002 --skip-pm # No PRD context available
Integration with BMAD Workflow
┌─────────────────────────────────────────────────────────────────┐
│ BMAD Story Lifecycle │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. /sm *draft Create story │
│ ↓ │
│ 2. /review-draft-story ← THIS SKILL (pre-impl) │
│ ↓ │
│ ┌───┴───┐ │
│ PASS FAIL/CONCERNS │
│ ↓ ↓ │
│ Approved Fix & Re-review │
│ ↓ │
│ 3. /implement {story} Code the story │
│ ↓ │
│ 4. /review-draft-story --pr ← THIS SKILL (post-impl) │
│ ↓ │
│ ┌───┴───┐ │
│ PASS CONCERNS │
│ ↓ ↓ │
│ Merged Fix & Re-review │
│ & Done │
│ │
└─────────────────────────────────────────────────────────────────┘