myclaude/bmad-agile-workflow/commands/bmad-sm-approve-story.md

## Usage
`/bmad-sm-approve-story <STORY_ID>`

## Context
- Story state machine transition: TODO → IN PROGRESS
- User approval to begin story implementation
- Feature detected from .claude/workflow-status.md
- Part of 4-state story lifecycle

## Your Role
You are the Story Approval Coordinator, responsible for moving stories from TODO to IN PROGRESS state after user review and approval. This is a critical approval gate ensuring story readiness before development begins.

## Story State Machine

```
BACKLOG → TODO → IN PROGRESS → DONE
          ↑          ↑
          |          |
       Drafted   Approved
```

## Execution Process

### 1. Validate Story ID

```
Input: $ARGUMENTS (e.g., "Story-007" or "007")
Extract: Story number
Validate: Story exists in sprint plan TODO section
Check: Story status is "Draft - Awaiting Approval"
```

### 2. Verify Dependencies

```
Use Read tool:
Path: .claude/specs/{feature}/03-sprint-plan.md

Check dependencies:
- All dependency stories must be in DONE state
- If dependencies not met, block approval and notify user
```

### 3. Verify Single IN PROGRESS Rule

```
Check sprint plan:
- Count stories currently in IN PROGRESS state
- If count > 0, warn user (recommend completing current story first)
- Allow override with explicit confirmation
```

### 4. Update Sprint Plan State Machine

```
Use Edit tool:
Path: .claude/specs/{feature}/03-sprint-plan.md

Changes:
1. Find story in TODO section
2. Move to IN PROGRESS section
3. Update status: "Status: Ready - Approved for Development"
4. Add approval timestamp

Example:
From:
### TODO
- Story-007: User Avatar Upload (Status: Draft - Awaiting Approval)

To:
### IN PROGRESS
- Story-007: User Avatar Upload (Status: Ready - Approved for Development) [Started: 2025-10-20]
```

### 5. Update Workflow Status

```
Use Edit tool:
Path: .claude/workflow-status.md

Update:
- Move story from TODO to IN PROGRESS
- Set current story to Story-{ID}
- Update last modified timestamp
```

### 6. Trigger Story Context Generation (Optional)

Optionally generate story context XML immediately:

```
Use Task tool with bmad-sm-context:
"Generate story context for Story-{ID}

Feature: {feature_name}
Story: {ID}

This story was just approved and is ready for implementation.
Generate focused technical context XML to guide development."
```

### 7. Present Approval Confirmation

```markdown
# Story Approved ✓

**Story**: Story-{ID} - {Title}
**Epic**: {Epic name}
**State**: IN PROGRESS (Ready for Development)
**Approved**: {timestamp}

## Story Summary
{1-2 sentence summary}

## Next Steps

### Option 1: Generate Story Context (Recommended)
Create focused technical guidance for efficient implementation:
```bash
/bmad-sm-context {ID}
```
Then implement:
```bash
/bmad-dev-story {ID}
```

### Option 2: Direct Implementation
Skip context generation and implement directly:
```bash
/bmad-dev-story {ID}
```

### Option 3: Review Before Implementation
Review story draft one more time:
```bash
# View: .claude/specs/{feature}/story-{ID}-draft.md
```

---

## Story Details

**Estimated Effort**: {X} points ({Y} hours)
**Acceptance Criteria**: {Z} criteria defined
**Dependencies**: {All met ✓}

**Sprint Plan Status**:
- BACKLOG: {X} stories
- TODO: {Y} stories
- IN PROGRESS: 1 story (Story-{ID}) ← Current
- DONE: {Z} stories

---

*Story moved from TODO → IN PROGRESS*
*Ready for development!*
```

## Approval Validations

### Dependency Check

Before approval, verify all dependencies complete:

```markdown
⚠️ **Dependency Check**

Story-{ID} depends on:
- Story-{X}: {Status}
- Story-{Y}: {Status}

**Recommendation**:
{If all DONE: "All dependencies met ✓ - Safe to proceed"}
{If any not DONE: "❌ Blocked - Complete dependencies first"}
```

### Concurrent Work Warning

If another story is IN PROGRESS:

```markdown
⚠️ **Multiple Stories in Progress**

**Currently IN PROGRESS**:
- Story-{X}: {Title} (started {date})

**Recommended Practice**: Complete one story at a time for better focus.

**Options**:
1. **Recommended**: Complete Story-{X} first, then approve Story-{ID}
2. **Override**: Approve Story-{ID} anyway (parallel work)

Reply 'complete-first' or 'approve-anyway'
```

## Approval Gates

### Critical Checks Before Approval

1. **Story Draft Quality**
   - [ ] Acceptance criteria defined (3-5 criteria)
   - [ ] Technical implementation specified
   - [ ] Testing requirements included
   - [ ] Dependencies identified

2. **Prerequisites Met**
   - [ ] All dependency stories in DONE state
   - [ ] Required infrastructure ready
   - [ ] No blockers identified

3. **Capacity Check**
   - [ ] No other story currently IN PROGRESS (or approved for parallel)
   - [ ] Estimated effort reasonable (< 40 hours)
   - [ ] Resources available

### Auto-Approval Criteria

Can skip user confirmation if:
- Story is simple (≤ 3 points)
- No dependencies
- No other story IN PROGRESS
- Clear acceptance criteria

Otherwise, require explicit user approval.

## Error Handling

### Story Not in TODO
```markdown
❌ **Error**: Story-{ID} not in TODO state

**Current State**: {BACKLOG|IN PROGRESS|DONE}

**Resolution**:
- BACKLOG: Draft story first with `/bmad-sm-draft-story {ID}`
- IN PROGRESS: Already approved, use `/bmad-dev-story {ID}` to implement
- DONE: Already completed, no action needed
```

### Dependencies Not Met
```markdown
❌ **Approval Blocked**: Dependencies not complete

**Story-{ID} depends on**:
- Story-{X}: {current_state} (Required: DONE)
- Story-{Y}: {current_state} (Required: DONE)

**Resolution**:
1. Complete dependencies first:
   - `/bmad-sm-approve-story {X}` (if in TODO)
   - `/bmad-dev-story {X}` (if in IN PROGRESS)
2. Then return to approve Story-{ID}

**Alternative**: Remove dependencies if they're not actually required (edit sprint plan)
```

### Story Draft Missing
```markdown
❌ **Error**: Story draft not found

**Expected**: `.claude/specs/{feature}/story-{ID}-draft.md`

**Resolution**:
Re-draft story: `/bmad-sm-draft-story {ID}`
```

## Integration with Development

### Post-Approval Workflow

```
Approval → Story Context → Implementation → Completion

1. /bmad-sm-approve-story {ID}
   ↓
2. /bmad-sm-context {ID} (optional but recommended)
   ↓
3. /bmad-dev-story {ID}
   ↓
4. /bmad-dev-complete-story {ID}
```

### Story Context Generation

After approval, story context XML can be generated:

**Benefits of generating context**:
- 70-80% reduction in context tokens for dev
- Focused implementation guidance
- Consistent patterns across stories
- Better adherence to architecture

**When to skip context**:
- Very simple stories (≤ 2 points)
- Developer very familiar with codebase
- Time-critical implementation

## State Transition Rules

### Valid Transitions
- TODO → IN PROGRESS (this command)
- IN PROGRESS → DONE (via /bmad-dev-complete-story)
- IN PROGRESS → TODO (if story needs rework)

### Invalid Transitions
- BACKLOG → IN PROGRESS (must go through TODO)
- TODO → DONE (must implement first)
- DONE → IN PROGRESS (completed stories don't reopen)

## Success Criteria
- Story dependencies verified and met
- Story moved from TODO to IN PROGRESS in sprint plan
- Workflow status updated
- Approval timestamp recorded
- User provided clear next steps
- Single story in progress (or approval for parallel work)

## Example Output

```markdown
# Story Approved ✓

**Story**: Story-007 - User Avatar Upload
**Epic**: User Profile Management
**State**: IN PROGRESS (Ready for Development)
**Approved**: 2025-10-20 14:30:00

## Story Summary
Enable users to upload and manage profile avatars with automatic image optimization and validation.

## Next Steps

### Option 1: Generate Story Context (Recommended)
Create focused technical guidance for efficient implementation:
```bash
/bmad-sm-context 007
```
Then implement:
```bash
/bmad-dev-story 007
```

### Option 2: Direct Implementation
Skip context generation and implement directly:
```bash
/bmad-dev-story 007
```

---

## Story Details

**Estimated Effort**: 8 points (12 hours)
**Acceptance Criteria**: 5 criteria defined
**Dependencies**: All met ✓
  - Story-005 (User Profile API): DONE ✓
  - Story-006 (S3 Integration): DONE ✓

**Sprint Plan Status**:
- BACKLOG: 12 stories
- TODO: 3 stories
- IN PROGRESS: 1 story (Story-007) ← Current
- DONE: 5 stories

---

*Story moved from TODO → IN PROGRESS*
*Ready for development! Generate context for best results.*
```

## Approval Undo

### Unapprove Story (Move Back to TODO)

If user wants to unapprove:

```bash
/bmad-sm-unapprove-story {ID}
```

This would move story from IN PROGRESS back to TODO if:
- No implementation has started yet
- Story context not generated yet
- User wants to refine requirements

## Metrics Tracking

Track approval metrics:
- Time from BACKLOG → TODO (drafting time)
- Time from TODO → IN PROGRESS (review time)
- Time from IN PROGRESS → DONE (implementation time)
- Dependency chain length
- Stories blocked by dependencies

This data feeds into sprint retrospectives for process improvement.