/create-epic-plan

name: create-epic-plan
description: Create an epic planning document by analyzing Jira tickets and codebase
argument-hint: <epic-key>

Epic Planning Document Generator

**Epic Key:** $ARGUMENTS

---

Workflow Chain

This command creates a comprehensive planning document (Overview Document) for an epic:

/create-epic-plan <epic-key>     → Creates Overview Document (YOU ARE HERE)
         ↓
/create-implementation-plan <overview-doc-url>  → Creates Implementation Plan
         ↓
/execute-ticket <ticket-key>     → Executes individual tickets

---

Phase 0: Context Retrieval

1. **Fetch the epic** from Jira using `{Epic_Key}`

2. **Extract from epic:**

• `{Epic_Title}` - The epic title/name
• `{Jira_Project}` - The Jira project URL
• Linked tickets

3. **Determine Confluence location:**

• Default: `/Epics/In Progress/{Epic_Key}/`
• If location unclear, ask user

4. **FAILURE CONDITION - Missing Information:**

If epic cannot be found or has no linked tickets:

**STOP and prompt the user:**

   I was unable to retrieve epic {Epic_Key}.

   Issue: [epic not found / no linked tickets / access denied]

   Please provide:
   1. Confirm the epic key is correct
   2. Jira Project URL: [paste link]
   3. Confluence publish location: [paste link or confirm default]

**DO NOT PROCEED** until confirmed.

5. **MANDATORY CHECKPOINT - Epic Confirmation:**

   Please confirm before I proceed:

   Epic Key: {Epic_Key}
   Epic Title: {Epic_Title}
   Linked Tickets: [count] tickets found
   Publish Location: [Confluence path]

   Is this correct? (Yes / No / Correct)

**DO NOT PROCEED** without explicit user confirmation.

---

Phase 1: Discovery

1. **Read all Jira tickets** linked to epic `{Epic_Key}`

• Use JQL query: `"Epic Link" = {Epic_Key}` to find all child tickets
• Extract acceptance criteria from each ticket
• Identify ticket dependencies and relationships
• Note any technical constraints mentioned

2. **Explore the codebase using parallel agents**

Launch these agents **in parallel** to analyze different aspects of the codebase:

| Agent | Task | Output for Section 11 | |-------|------|----------------------| | `Explore` | Find all files/modules affected by this epic based on ticket requirements | → Affected Modules | | `Explore` | Discover API patterns, middleware conventions, response formats | → Patterns Discovered (API) | | `Explore` | Discover component patterns, naming conventions, state management | → Patterns Discovered (Components) | | `Explore` | Find test file locations, testing framework, fixture patterns | → Test Locations & Conventions | | `Explore` | Find similar features that can serve as implementation references | → Reference Implementations |

**Agent Prompts:**

   Agent 1 - Affected Modules:
   "Find all directories and files that will be affected by implementing [epic summary].
   List the key modules, their purposes, and how they relate to the epic requirements."

   Agent 2 - API Patterns:
   "Analyze the API layer in packages/server/. Document the route structure,
   middleware patterns, authentication approach, response formats, and error handling conventions."

   Agent 3 - Component Patterns:
   "Analyze the frontend components in packages/web/src/components/. Document naming
   conventions, folder structure, state management patterns, and common UI patterns used."

   Agent 4 - Test Patterns:
   "Analyze the test structure in tests/ and e2e/. Document the testing framework,
   file naming conventions, available test utilities, fixture patterns, and mock approaches."

   Agent 5 - Reference Implementations:
   "Find existing features similar to [epic summary] that can serve as templates.
   List the files and explain what patterns from each can be reused."

**Wait for all agents to complete**, then synthesize findings into Section 11.

3. **Document unknowns:**

• Missing information or ambiguous requirements
• Technical decisions that need architectural input
• Integration points that need clarification

---

Phase 2: Planning Document Creation

Create a comprehensive planning document with these sections:

1. Epic Overview

• **Purpose:** What problem does this epic solve?
• **User Value:** How does this improve the user experience?
• **Scope:** What is included/excluded from this epic?
• **Key Stakeholders:** Who is impacted by this work?

2. Epic Goals & Success Metrics

• **Primary Goal:** Main objective of this epic
• **Success Metrics:** How will we measure success?
• **KPIs:** Quantifiable outcomes (if applicable)

3. Requirements Summary

• **Functional Requirements:** What the system must do
• **Non-Functional Requirements:** Performance, security, accessibility, etc.
• **Business Rules:** Constraints and validation rules
• **Edge Cases:** Error handling and boundary conditions

4. Technical Change Overview

List all technical changes with risk assessment. For each change:

| Component | Type | Description | Risk Score | Dependencies | |-----------|------|-------------|------------|--------------| | [file/component] | [New/Enhancement/Refactor/Fix] | [summary] | [Low/Med/High] | [blockers] |

5. Impact Analysis

• **Codebase Impact:** Files, components, APIs affected
• **Data Model Changes:** Database migrations required
• **API Changes:** New endpoints, modified contracts, breaking changes
• **UI/UX Changes:** New screens, modified flows
• **Migration Strategy:** How will existing users/data transition?
• **Rollback Plan:** How can this be safely reverted?
• **Tradeoffs:** What compromises are being made and why?

6. Testing Strategy

• **Unit Testing:** Coverage targets (aim for 90% branch coverage)
• **Integration Testing:** Cross-component interactions
• **API Testing:** Endpoint validation and error handling
• **Test Data:** Fixtures and mock data requirements
• **Coverage Goals:** Specific are