Story Breakdown Skill

When to Use This Skill

Use this skill when:

• You have an epic file in docs/epics/
• You need to break down the epic into story-level work items
• User asks to "create stories" or "break down epic E{X}"
• Ready to plan implementation details for an epic

What This Skill Does

Reads an epic file and generates individual story files in docs/stories/ directory. Each story represents a user-facing feature or capability (typically 1-3 days of development).

Workflow

Step 1: Read Epic & PRD

1. Read the epic file (e.g., docs/epics/epic-e1-telephony.md)
2. Read docs/prd.md for additional context
3. Read docs/system-architecture.md for technical context
4. Understand epic goals, scope, and dependencies

Step 2: Identify Stories

Stories should:
- Deliver user-facing value
- Be completable in 1-3 days
- Have clear acceptance criteria
- Be testable independently
- Follow format: "As a {user}, I want {feature}, so that {benefit}"

For each "Kern-Story" listed in epic, create a detailed story file.

Step 3: Create Story Files

For each story, create file: docs/stories/story-{epic-id}-s{num}-{date}.md

Example filenames:
- docs/stories/story-e1-s001-2025-11-02.md
- docs/stories/story-e1-s002-2025-11-02.md
- docs/stories/story-e2-s001-2025-11-02.md

Step 4: Story File Structure

Each story file should contain:

# Story {Epic-ID}-S{Num} — {Story Name}

**Epic:** {Epic ID and Name}
**Status:** Ready for Implementation
**Date:** {YYYY-MM-DD}

---

## User Story

**As a** {user role},
**I want** {feature/capability},
**So that** {business value/benefit}.

---

## What to Build

{Clear, concise description of what needs to be implemented}

A {component/feature} that:
1. {Capability 1}
2. {Capability 2}
3. {Capability 3}

---

## Prerequisites - READ FIRST

### Required Documentation
**MUST READ before coding:**
- \`/docs/system-architecture.md\` - Section {X}
- \`/docs/prd.md\` - {Relevant section}
- \`/docs/epics/{epic-file}.md\` - Epic requirements

### System Context
- **Platform:** {Technology stack}
- **Runtime:** {Runtime environment}
- **Database:** {Database info}
- **Language:** {Programming language}

### External Services Integration
- **Service 1:** {How it integrates}
- **Service 2:** {How it integrates}

---

## 🛑 STOP - USER VERIFICATION REQUIRED

**⚠️ CODING AGENT: DO NOT PROCEED until user confirms ALL items below.**

**ASK USER and WAIT for response before writing any code:**

1. **{Configuration Item 1}:**
   - **Ask:** "{Specific question}"
   - **If user doesn't know:** {Guidance}
   - **Wait for:** {Expected answer}

2. **{Configuration Item 2}:**
   - **Ask:** "{Specific question}"
   - **If NO:** STOP and tell user: "{Instructions}"
   - **If YES:** Request: {What you need}

---

## 🛑 IMPLEMENTATION CHECKPOINTS

**Throughout implementation, STOP and wait for user at these points:**

### Before Step 1 ({Step Name})
- **If {condition}:** {Stop and ask user}
- **If {error}:** STOP, report error, wait for user to resolve

### Before Step 2 ({Step Name})
- **Ask:** "{Question before proceeding}"
- **Wait for:** Explicit user confirmation

---

## 🛑 MISSING CONTEXT - STOP IMMEDIATELY

**If you encounter any of these situations, STOP and ask user:**

1. **Unclear requirements:** {Specific trigger}
2. **Conflicting documentation:** {Specific trigger}
3. **Missing dependency versions:** {Specific trigger}
4. **Ambiguous error messages:** {Specific trigger}
5. **External service documentation unclear:** {Specific trigger}

**DO NOT:**
- ❌ Guess or make assumptions
- ❌ Skip verification items
- ❌ Proceed with placeholder values
- ❌ Continue if tests fail

---

## Project Structure (To Be Created)

\`\`\`
project/
├── {directory1}/
│   ├── {file1}          # 👈 THIS STORY
│   └── {file2}          # 👈 THIS STORY
├── {directory2}/
│   └── {file3}          # 👈 THIS STORY
└── docs/
    └── stories/
        └── {this-file}.md  # 👈 YOU ARE HERE
\`\`\`

---

## Implementation Steps

### Step 1: {Phase Name}
{Description}

**Tasks:**
- [ ] {Task 1}
- [ ] {Task 2}

**Acceptance Criteria:**
- ✅ {Criterion 1}
- ✅ {Criterion 2}

### Step 2: {Phase Name}
{Description}

**Tasks:**
- [ ] {Task 1}
- [ ] {Task 2}

**Acceptance Criteria:**
- ✅ {Criterion 1}
- ✅ {Criterion 2}

---

## Testing Requirements

**Unit Tests:**
- Test {component 1}
- Test {component 2}

**Integration Tests:**
- Test {integration 1}
- Test {integration 2}

**Manual Testing:**
1. {Manual test step 1}
2. {Manual test step 2}

---

## Definition of Done

- [ ] All implementation steps completed
- [ ] All tests pass
- [ ] No console errors
- [ ] German language used for all user-facing text
- [ ] Code follows architecture patterns
- [ ] Documentation updated
- [ ] QA validation passed (backend + frontend if applicable)

---

## Dependencies

**External Services:**
- {Service 1}: {What's needed}
- {Service 2}: {What's needed}

**Other Stories:**
- Depends on: {Story ID} (if any)
- Blocks: {Story ID} (if any)

---

## Notes for Implementation

{Any additional context or guidance}

Step 5: Update Epic File

Update the epic file to reference the new stories:

**Status:** In Progress (2/5 stories completed)

**Stories:**
- ✅ [E1-S001: Twilio Webhook Handler](../stories/story-e1-s001-2025-11-02.md) - Completed
- 🔄 [E1-S002: Health Check System](../stories/story-e1-s002-2025-11-02.md) - In Progress
- ⬜ [E1-S003: Failover Logic](../stories/story-e1-s003-2025-11-02.md) - Not Started

Important Story Guidelines

DO:

• ✅ Include all 🛑 STOP checkpoints
• ✅ List specific prerequisites and documentation to read
• ✅ Define clear acceptance criteria
• ✅ Specify external services integration details
• ✅ Provide project structure context
• ✅ Use German for user-facing descriptions
• ✅ Make stories self-contained (can be implemented independently)

DON'T:

• ❌ Make stories too large (>3 days)
• ❌ Leave requirements ambiguous
• ❌ Skip STOP checkpoints
• ❌ Assume context from other stories
• ❌ Omit testing requirements

Output

After running this skill, you should have:

• ✅ Multiple story files in docs/stories/
• ✅ Each story clearly defined with 🛑 STOP checkpoints
• ✅ Epic file updated with story links
• ✅ User understands implementation order

Next Step

After creating stories, user should:

1. Select a story to start with
2. Run /task-breakdown skill to break that story into tasks
3. Or directly implement the story if it's simple enough