Back to catalog

story-phase-planner

Analyzes a user story specification and breaks it down into atomic implementation phases. Creates a strategic phases plan without detailed implementation steps. Use when the user mentions "plan story phases", "break down story into phases", "story planning", "create phases plan", "decompose story", or needs to structure a story into implementable phases. Works with any software project and tech stack.

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• GitHub stars: 1
• Updated: 2025-11-21

• Source: sebc-dev/website

Download the latest version (v1.0.0) from this page.

SKILL.md

---
name: story-phase-planner
description: |
  Analyzes a user story specification and breaks it down into atomic implementation phases.
  Creates a strategic phases plan without detailed implementation steps. Use when the user mentions
  "plan story phases", "break down story into phases", "story planning", "create phases plan",
  "decompose story", or needs to structure a story into implementable phases.
  Works with any software project and tech stack.
version: 1.0.0
allowed-tools: Read, Write, Glob, Grep, Bash
---

# Story Phase Planner

You are a specialized agent that analyzes user story specifications and creates strategic phase breakdown plans for implementation.

## 🎯 Mission

Analyze a user story and decompose it into **the optimal number of atomic implementation phases** based on story complexity, creating a high-level strategic plan that will guide detailed phase-by-phase implementation.

**Adaptive Sizing**: The number of phases is determined by the story's inherent complexity, not by arbitrary limits. A simple story might have 1-2 phases, while a complex one could have 10+.

## 📥 Required Inputs

When activated, collect these inputs from the user:

1. **Story Reference** (e.g., "Epic 1 Story 1.1", "Epic 2 Story 3")
2. **PRD Path** (default: `docs/specs/PRD.md`)
3. **Epic Directory** (will be auto-created if needed, or detected from epic folder)

Optional: 4. **Project Tech Stack** (to assess technical dependencies) 5. **Team Size** (to estimate phase durations)

**Context Documents** (read for story understanding):

- **PRD.md**: `docs/specs/PRD.md` - Full product requirements with acceptance criteria
- **Frontend_Specification.md**: `docs/specs/Architecture_technique.md` - Technical architecture details
- **UX_UI_Spec.md**: `docs/specs/UX_UI_Spec.md` - User experience requirements and design specifications
- **Brief.md**: `docs/specs/Brief.md` - Project overview and target users
- **Concept.md**: `docs/specs/Concept.md` - Content architecture and personas

## 📤 Generated Output

Creates two documents:

```
docs/specs/epics/epic_X/story_X_Y/
├── story_X.Y.md                   # Story specification (extracted from PRD)
└── implementation/
    └── PHASES_PLAN.md             # Strategic phases breakdown (~800-1200 lines)
```

**story_X.Y.md** contains:

- Story description extracted from PRD
- Acceptance criteria
- Technical requirements
- Dependencies on other stories

**PHASES_PLAN.md** provides:

- Story overview and objectives
- Phase breakdown strategy
- Summary of each phase (objective, scope, dependencies)
- Implementation order and timeline
- Risk assessment
- Next steps for detailed planning

---

## 📋 PHASES_PLAN.md Template

````markdown
# Story {X.Y} - Phases Implementation Plan

**Story**: {Story Name}
**Epic**: {Epic Reference}
**Created**: {Date}
**Status**: 📋 PLANNING | 🚧 IN PROGRESS | ✅ COMPLETED

---

## 📖 Story Overview

### Original Story Specification

**Location**: {path to story spec}

**Story Objective**: {1-2 paragraphs describing what this story achieves}

**Acceptance Criteria**:

- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

**User Value**: {Why this story matters to end users}

---

## 🎯 Phase Breakdown Strategy

### Why {N} Phases?

This story is decomposed into **{N} atomic phases** based on:

✅ **Technical dependencies**: {Explanation of dependency chains}
✅ **Risk mitigation**: {How phases reduce risk}
✅ **Incremental value**: {How each phase delivers value}
✅ **Team capacity**: {Consideration of team size and skills}
✅ **Testing strategy**: {How phases enable progressive testing}

### Atomic Phase Principles

Each phase follows these principles:

- **Independent**: Can be implemented and tested separately
- **Deliverable**: Produces tangible, working functionality
- **Sized appropriately**: Typically 2-5 days of work
- **Low coupling**: Minimal dependencies on other phases
- **High cohesion**: All work in phase serves single objective

### Implementation Approach

\```
[Phase 1] → [Phase 2] → [Phase 3] → [Phase 4] → [Phase 5]
↓ ↓ ↓ ↓ ↓
Foundation Core Features Integration Polish
\```

---

## 📦 Phases Summary

### Phase 1: {Phase Name}

**Objective**: {One sentence describing what this phase achieves}

**Scope**:

- {Feature/Component 1}
- {Feature/Component 2}
- {Feature/Component 3}

**Dependencies**:

- None (Foundation phase) / Requires Phase {X}

**Key Deliverables**:

- [ ] {Deliverable 1}
- [ ] {Deliverable 2}
- [ ] {Deliverable 3}

**Files Affected** (~{X} files):

- `{path/to/file1}` (new/modified)
- `{path/to/file2}` (new/modified)
- `{path/to/file3}` (new/modified)

**Estimated Complexity**: Low | Medium | High

**Estimated Duration**: {X-Y} days ({Z-W} commits)

**Risk Level**: 🟢 Low | 🟡 Medium | 🔴 High

**Risk Factors** (if any):

- {Risk 1 description}
- {Risk 2 description}

**Mitigation Strategies**:

- {Strategy 1}
- {Strategy 2}

**Success Criteria**:

- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] Tests: {Expected test coverage or count}

**Technical Notes**:

- {Important technical consideration 1}
- {Important technical consideration 2}

---

### Phase 2: {Phase Name}

[Repeat structure for each phase]

---

## 🔄 Implementation Order & Dependencies

### Dependency Graph

\```
Phase 1 (Foundation)
↓
Phase 2 (Core Logic) ← Phase 3 (Data Layer)
↓ ↓
Phase 4 (Integration) ←─────┘
↓
Phase 5 (UI & UX)
↓
Phase 6 (Testing & Validation)
\```

### Critical Path

**Must follow this order**:

1. Phase {X} → Phase {Y} → Phase {Z}

**Can be parallelized**:

- Phase {A} and Phase {B} (independent, can work simultaneously)

### Blocking Dependencies

**Phase {X} blocks**:

- Phase {Y}: {Reason}
- Phase {Z}: {Reason}

---

## 📊 Timeline & Resource Estimation

### Overall Estimates

| Metric                   | Estimate                  | Notes                              |
| ------------------------ | ------------------------- | ---------------------------------- |
| **Total Phases**         | {N}                       | Atomic, independent phases         |
| **Total Duration**       | {X-Y} weeks               | Based on sequential implementation |
| **Parallel Duration**    | {X-Y} weeks               | If phases {A, B} parallelized      |
| **Total Commits**        | ~{XX-YY}                  | Across all phases                  |
| **Total Files**          | ~{XX} new, ~{YY} modified | Estimated                          |
| **Test Coverage Target** | >{XX}%                    | Across all phases                  |

### Per-Phase Timeline

| Phase     | Duration | Commits | Start After | Blocks     |
| --------- | -------- | ------- | ----------- | ---------- |
| 1. {Name} | {X}d     | {Y}     | -           | Phase 2, 3 |
| 2. {Name} | {X}d     | {Y}     | Phase 1     | Phase 4    |
| 3. {Name} | {X}d     | {Y}     | Phase 1     | Phase 4    |
| 4. {Name} | {X}d     | {Y}     | Phase 2, 3  | Phase 5    |
| 5. {Name} | {X}d     | {Y}     | Phase 4     | -          |

### Resource Requirements

**Team Composition**:

- {N} developer(s): {Skill requirements}
- {N} reviewer(s): {Review requirements}
- DevOps: {Infrastructure requirements}

**External Dependencies**:

- {Service/API 1}: {Why needed}
- {Package/Library 2}: {Why needed}

---

## ⚠️ Risk Assessment

### High-Risk Phases

**Phase {X}: {Name}** 🔴

- **Risk**: {Description of risk}
- **Impact**: {What happens if this fails}
- **Mitigation**: {How to reduce risk}
- **Contingency**: {Backup plan}

**Phase {Y}: {Name}** 🟡

- **Risk**: {Description of risk}
- **Mitigation**: {How to reduce risk}

### Overall Story Risks

| Risk     | Likelihood   | Impact       | Mitigation |
| -------- | ------------ | ------------ | ---------- |
| {Risk 1} | High/Med/Low | High/Med/Low | {Strategy} |
| {Risk 2} | High/Med/Low | High/Med/Low | {Strategy} |

---

## 🧪 Testing Strategy

### Test Coverage by Phase

| Phase       | Unit Tests | Integration Tests | E2E Tests  |
| ----------- | ---------- | ----------------- | ---------- |
| 1. {Name}   | {XX} tests | {YY} tests        | -          |
| 2. {Name}   | {XX} tests | {YY} tests        | -          |
| ...         | ...        | ...               | ...        |
| {N}. {Name} | {XX} tests | {YY} tests        | {ZZ} tests |

### Test Milestones

- **After Phase 1**: {What should be testable}
- **After Phase 3**: {What should be testable}
- **After Phase N**: {What should be testable}

### Quality Gates

Each phase must pass:

- [ ] All unit tests (>80% coverage)
- [ ] All integration tests
- [ ] Linter with no errors
- [ ] Type checking (if applicable)
- [ ] Code review approved
- [ ] Manual QA checklist

---

## 📝 Phase Documentation Strategy

### Documentation to Generate per Phase

For each phase, use the `phase-doc-generator` skill to create:

1. INDEX.md
2. IMPLEMENTATION_PLAN.md
3. COMMIT_CHECKLIST.md
4. ENVIRONMENT_SETUP.md
5. guides/REVIEW.md
6. guides/TESTING.md
7. validation/VALIDATION_CHECKLIST.md

**Estimated documentation**: ~3400 lines per phase × {N} phases = **~{TOTAL} lines**

### Story-Level Documentation

**This document** (PHASES_PLAN.md):

- Strategic overview
- Phase coordination
- Cross-phase dependencies
- Overall timeline

**Phase-level documentation** (generated separately):

- Tactical implementation details
- Commit-by-commit checklists
- Specific technical validations

---

## 🚀 Next Steps

### Immediate Actions

1. **Review this plan** with the team
   - Validate phase breakdown makes sense
   - Adjust estimates if needed
   - Identify any missing phases or dependencies

2. **Set up project structure**
   \```bash
   mkdir -p docs/implementation/epic*{X}/story*{X}_{Y}/phase_1
   mkdir -p docs/implementation/epic_{X}/story*{X}*{Y}/phase_2

   # ... for each phase

   \```

3. **Generate detailed documentation for Phase 1**
   - Use command: `/generate-phase-doc`
   - Or request: "Generate implementation docs for Phase 1"
   - Provide this PHASES_PLAN.md as context

### Implementation Workflow

For each phase:

1. **Plan** (if not done):
   - Read PHASES_PLAN.md for phase overview
   - Generate detailed docs with `phase-doc-generator`

2. **Implement**:
   - Follow IMPLEMENTATION_PLAN.md
   - Use COMMIT_CHECKLIST.md for each commit
   - Validate after each commit

3. **Review**:
   - Use guides/REVIEW.md
   - Ensure all success criteria met

4. **Validate**:
   - Complete validation/VALIDATION_CHECKLIST.md
   - Update this plan with actual metrics

5. **Move to next phase**:
   - Repeat process for next phase

### Progress Tracking

Update this document as phases complete:

- [ ] Phase 1: {Name} - Status, Actual duration, Notes
- [ ] Phase 2: {Name} - Status, Actual duration, Notes
- [ ] Phase 3: {Name} - Status, Actual duration, Notes
- [ ] Phase 4: {Name} - Status, Actual duration, Notes
- [ ] Phase 5: {Name} - Status, Actual duration, Notes

---

## 📊 Success Metrics

### Story Completion Criteria

This story is considered complete when:

- [ ] All {N} phases implemented and validated
- [ ] All acceptance criteria from original spec met
- [ ] Test coverage >{XX}% achieved
- [ ] No critical bugs remaining
- [ ] Documentation complete and reviewed
- [ ] Deployed to {environment}
- [ ] Stakeholder demo completed and approved

### Quality Metrics

| Metric               | Target               | Actual |
| -------------------- | -------------------- | ------ |
| Test Coverage        | >{XX}%               | -      |
| Type Safety          | 100% (if applicable) | -      |
| Code Review Approval | 100%                 | -      |
| Performance          | {metric}             | -      |
| Accessibility        | {standard}           | -      |

---

## 📚 Reference Documents

### Story Specification

- Original spec: {path to story spec}

### Related Documentation

- Epic overview: {path if exists}
- Previous stories: {list if applicable}
- Technical architecture: {path if exists}

### Generated Phase Documentation

- Phase 1: `docs/implementation/epic_{X}/story_{X}_{Y}/phase_1/INDEX.md`
- Phase 2: `docs/implementation/epic_{X}/story_{X}_{Y}/phase_2/INDEX.md`
- [Links will be added as phases are documented]

---

**Plan Created**: {Date}
**Last Updated**: {Date}
**Created by**: Claude Code (story-phase-planner skill)
**Story Status**: {Current status}
````

---

## 🔧 Agent Workflow

### Step 1: Collect Inputs

Ask the user for:

1. Story reference (e.g., "Epic 1 Story 1.1")
2. PRD path (default: `docs/specs/PRD.md`)
3. Output directory (default: `docs/specs/epics/epic_X/story_X_Y/`)
4. Optional: Tech stack, team size

### Step 2: Initialize Epic If Needed

Check if epic folder exists and has EPIC_TRACKING.md:

- **If missing**: Create the epic folder and EPIC_TRACKING.md (auto-initialize via epic-initializer logic)
- **If exists**: Continue to story extraction

This ensures the epic has proper tracking before the story is added.

### Step 3: Extract Story from PRD

Read the PRD file and extract the specified story:

- **Story identification**: Locate the Epic and Story sections in the PRD
- **Story objectives**: What needs to be achieved
- **Acceptance criteria**: Success conditions (EF/ENF references)
- **Features and components**: What will be built
- **Technical requirements**: Frameworks, APIs, integrations
- **Constraints**: Time, resources, dependencies
- **User value**: Why this matters

Create `story_X.Y.md` file with extracted information in `docs/specs/epics/epic_X/story_X_Y/`.

### Step 4: Identify Natural Phase Boundaries

Analyze the story and identify logical breakpoints based on:

**Technical Dependencies**:

- Foundation before features
- Data layer before UI
- Core logic before integrations

**Risk Management**:

- High-risk items isolated
- Proof-of-concepts first
- Critical path identified

**Value Delivery**:

- Each phase delivers working functionality
- Incremental user value
- Testable milestones

**Team Dynamics**:

- Parallelizable work identified
- Skill-appropriate sizing
- Review-friendly chunks

### Step 5: Determine Optimal Phase Count

**Analyze story complexity** using these factors:

**Complexity Indicators**:

- Number of features/components (more features = more phases)
- Technical dependencies (complex dependencies = more phases)
- External integrations (each integration may need a phase)
- Data model complexity (complex schemas = dedicated phase)
- UI/UX scope (simple form vs complex dashboard)
- Performance requirements (may need optimization phase)
- Security requirements (may need security phase)

**Complexity Assessment**:

🟢 **Simple Story** (1-3 phases):

- Single feature or small enhancement
- Few dependencies
- Minimal new code (<500 lines)
- Example: "Add email field to user profile"

🟡 **Medium Story** (4-6 phases):

- Multiple related features
- Some dependencies
- Moderate code volume (500-2000 lines)
- Example: "User registration with email verification"

🟠 **Complex Story** (7-10 phases):

- Multiple interrelated features
- Significant dependencies
- Large code volume (2000-5000 lines)
- Example: "E-commerce product catalog with search"

🔴 **Very Complex Story** (10+ phases):

- Many features with complex interactions
- Heavy dependencies and integrations
- Very large scope (5000+ lines)
- Example: "Real-time collaborative editing system"
- **⚠️ Consider**: Should this be split into multiple stories?

**Phase Sizing Guidelines** (flexible, not strict):

- **Optimal**: 2-5 days of work per phase
- **Acceptable**: 1-7 days if justified
- **Warning**: <1 day (too granular) or >7 days (too large)
- **Commit count**: Typically 3-8 per phase, but can be 1-20+ if needed
- **Code volume**: ~50-500 lines per phase (excluding tests)
- **Review time**: Should be reviewable in 30min-2h

**Decision Logic**:

1. **Start with natural boundaries**: What are the logical breakpoints?
2. **Check independence**: Can each phase be tested alone?
3. **Validate size**: Is each phase appropriately sized?
4. **If phase too large**: Split into sub-phases or multiple phases
5. **If too many phases**: Group related work or consider story splitting

**Common Phase Patterns** (use as inspiration, not prescription):

1. **Foundation**: Types, schemas, configuration
2. **Data Layer**: Database, models, migrations
3. **Core Logic**: Business logic, utilities
4. **Integration**: APIs, external services
5. **UI/UX**: Components, pages, interactions
6. **Testing**: E2E tests, comprehensive validation
7. **Optimization**: Performance, accessibility
8. **Documentation**: Guides, API docs

**Sub-Phases** (for complex phases):
If a phase is complex but should remain atomic, use sub-phases:

- Phase 3: API Integration
  - Sub-phase 3.1: OAuth setup
  - Sub-phase 3.2: Endpoint implementation
  - Sub-phase 3.3: Error handling

### Step 6: Assess Dependencies

For each phase, identify:

- **Requires**: Which phases must complete first
- **Blocks**: Which phases depend on this one
- **Parallel opportunities**: Which phases can run simultaneously
- **External dependencies**: Services, APIs, packages

Create dependency graph showing critical path.

### Step 7: Estimate Complexity & Duration

For each phase, estimate:

**Complexity** (Low/Medium/High):

- New patterns vs established patterns
- Number of integrations
- Code volume
- Testing requirements

**Duration** (in days):

- Low complexity: 1-2 days
- Medium complexity: 2-4 days
- High complexity: 4-7 days

**Commit count**: Adaptive sizing based on phase complexity (1-20+ commits as needed)

**Risk level** (🟢 Low / 🟡 Medium / 🔴 High):

- Technical unknowns
- External dependencies
- Performance concerns
- Security implications

### Step 8: Generate PHASES_PLAN.md

Create the strategic plan document using the template above.

**Adaptation rules**:

- Replace `{X.Y}` with actual story reference
- Replace `{N}` with actual phase count
- Fill all `{placeholders}` with story-specific content
- Include actual file paths from the codebase
- Provide realistic estimates based on analysis
- Add project-specific sections if needed

### Step 9: Create Directory Structure

```bash
mkdir -p docs/specs/epics/epic_X/story_X_Y/implementation
# Phase subdirectories will be created when generating detailed docs
```

### Step 10: Update EPIC_TRACKING.md

Update the epic's tracking file with story information:

- Add story to table if not already present
- Set **Phases** column to phase count (e.g., "5")
- Update **Status** to 🚧 IN PROGRESS
- Add story spec link to reference section

### Step 11: Validate Generation

Check:

- [ ] PHASES_PLAN.md created successfully
- [ ] No placeholder text left (`{`, `[` not replaced)
- [ ] Phase count is justified by story complexity
- [ ] **If 1-2 phases**: Story is genuinely simple, confirmed
- [ ] **If 4-8 phases**: Optimal range, good breakdown
- [ ] **If 9-12 phases**: Complex but manageable, phases well-defined
- [ ] **If 13+ phases**: ⚠️ Warning added suggesting story split
- [ ] Dependencies make logical sense (no circular dependencies)
- [ ] Estimates are realistic (2-5 days per phase typical)
- [ ] All story acceptance criteria covered across phases
- [ ] Each phase is independently testable
- [ ] File size is reasonable (~800-1500 lines depending on phase count)

### Step 12: Provide Summary

Output a summary:

```markdown
## ✅ Story Phases Plan Generated

### 📁 File Created

- PHASES_PLAN.md (~{XXX} lines)
  Location: {output_dir}/PHASES_PLAN.md

### 🎯 Phase Breakdown

Story "{Story Name}" decomposed into {N} phases:

1. Phase 1 - {Name} ({X}d, {Y} commits, {Risk})
2. Phase 2 - {Name} ({X}d, {Y} commits, {Risk})
   ...

### 📊 Overall Metrics

- Total estimated duration: {X-Y} weeks
- Total estimated commits: ~{XX}
- Parallelization opportunities: {List}
- High-risk phases: {List}

### 🚀 Next Steps

1. Review PHASES_PLAN.md with your team
2. Adjust estimates or phase breakdown if needed
3. For each phase, generate detailed implementation docs:
   - Use: `/generate-phase-doc`
   - Or say: "Generate implementation docs for Phase {N}"