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

Fetch the epic from Jira using {Epic_Key}
Extract from epic:
- {Epic_Title} - The epic title/name
- {Jira_Project} - The Jira project URL
- Linked tickets
Determine Confluence location:
- Default: /Epics/In Progress/{Epic_Key}/
- If location unclear, ask user

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.

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

Read all Jira tickets linked to epic {Epic_Key}
- Use JQL query: Parent = {Epic_Key} to find all child tickets
- Extract acceptance criteria from each ticket
- Identify ticket dependencies and relationships
- Note any technical constraints mentioned

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.

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 areas requiring high coverage

7. User Behavior Testing

E2E Scenarios: Critical user journeys to validate
Acceptance Test Cases: Scenarios derived from requirements
User Flows: Step-by-step validation paths
Regression Testing: Existing flows that must not break

8. Implementation Notes

Patterns to Follow: Existing code patterns to replicate
Architecture Decisions: Key technical choices and rationale
Technical Debt: Known shortcuts or future improvements
Security Considerations: Authentication, authorization, data protection

9. Acceptance Criteria

Definition of done for this epic:

All functional requirements implemented
Test coverage meets targets (90% branch coverage)
Documentation updated
Security review completed (if applicable)
Performance benchmarks met (if applicable)
Accessibility standards met (if applicable)

10. Open Questions & Risks

Blockers: Items preventing progress
Unknowns: Information still needed
Assumptions: Things we're assuming to be true
Risks: Potential issues and mitigation strategies

11. Codebase Analysis

Capture findings from codebase exploration to inform the implementation plan:

Affected Modules:

List directories and modules that will be modified
Example: packages/server/routes/ - API endpoints affected

Patterns Discovered:

API conventions (route structure, middleware patterns, response formats)
Test patterns (framework, file locations, fixture patterns)
Component patterns (naming, structure, state management)
Database patterns (query patterns, transaction handling)

Reference Implementations:

Similar features that can serve as templates
Example: "See packages/web/src/components/events/ for CRUD component patterns"

Test Locations & Conventions:

Unit tests: tests/unit/ - pattern: [feature].test.ts
Integration tests: tests/integration/ - pattern: [endpoint].test.ts
E2E tests: e2e/ - pattern: [flow].spec.ts
Test utilities available: List helpers, fixtures, mocks

12. Linked Tickets

Epic: {Epic_Key} - {Epic_Title} Jira Project: {Jira_Project}

Key	Summary	Type	Story Points
TICKET-123	Ticket summary	Task/Bug/Story	X

Use JQL Parent = {Epic_Key} to fetch current ticket list.

Risk Assessment Framework

Evaluate each technical change across 7 dimensions (score 1-3 each):

Dimension	Low (1)	Medium (2)	High (3)
Scope	≤3 files, isolated change	4-10 files, single feature	10+ files, cross-cutting
Dependencies	All prerequisites exist	Some foundation work needed	Requires significant groundwork
Blocking Factor	Independent work	Soft dependency for 1-2 tickets	Hard blocker for multiple streams
Stability	Well-defined, existing patterns	Some unknowns, new patterns	Novel approach, high uncertainty
UX Impact	Backend/internal only	Secondary flows affected	Core user journey affected
Testing Complexity	Simple assertions, existing fixtures	New mocks/fixtures needed, async flows	Complex integration, E2E required, hard to isolate
Reversibility	Easily reverted, no data changes	Moderate effort to rollback	Database migrations, breaking API changes, one-way door

Risk Levels:

7-11 (Low): Proceed with standard implementation
12-16 (Medium): Incremental delivery, extra code review
17-21 (High): Spike/POC first, decompose further, architectural review required

Phase 3: Review & Publish

MANDATORY CHECKPOINT - Document Review:

Before publishing, present the complete planning document to the user:

## Planning Document Preview for {Epic_Key}

[Full planning document content]

---

Gaps/Unknowns Identified:
- [List any missing information]
- [Technical decisions needing input]
- [High-risk changes requiring spikes]

Ready to publish this planning document to Confluence? (Yes / No / Modify)

Yes → Publish to Confluence
No → Ask what changes are needed
Modify → User provides feedback, regenerate and re-confirm

DO NOT PUBLISH without explicit user approval.

Phase 4: Publish & Output

Publish to Confluence at: /epics/In Progress/{Epic_Key}/
- Page title: "{Epic_Key} {Epic_Title}"
Verify the document was published successfully
Get the published document URL ({Overview_Document})

Failure Conditions

Condition	Action
Epic key not found	Error message, ask user to verify epic key
No linked tickets	Warn user, ask if they want to continue with minimal document
Confluence location invalid	Ask user for correct location
Missing Jira/Confluence access	Provide instructions for credential setup
Codebase exploration inconclusive	Document unknowns, proceed with available information

Output

When complete, you MUST provide:

## Epic Planning Complete!

**Overview Document:** {Overview_Document}

### Summary
- Epic: {Epic_Key} - {Epic_Title}
- Tickets Analyzed: [count]
- Technical Changes: [count]
- Risk Profile: [X low, Y medium, Z high]
- Test Coverage Target: 90% branch coverage

### Open Questions
1. [Question needing clarification]
2. [Technical decision needing input]

### Next Step
Run the following command to generate the implementation plan:

/create-implementation-plan {Overview_Document}

CRITICAL: The Overview Document URL is required for the next step in the workflow chain.

Agent Delegation

Before creating the planning document:

Codebase Analysis: Thoroughly explore existing patterns, architecture, and conventions
Architecture Review: Have proposed structure reviewed for completeness
Deep Exploration: Understand current implementation, affected components, dependencies, and test coverage
Design Review: Validate approach for scalability, maintainability, and alignment with existing patterns

/create-epic-plan