Epic Management

Organize related work units into meaningful, trackable initiatives.

Epics group related stories, bugs, and tasks into cohesive initiatives. They provide high-level progress tracking, prefix-to-epic mapping, and strategic visibility across your entire project. Think of them as chapters in your project's story—each epic represents a significant body of work with a clear goal.

The Problem: Lost Context Across Related Work

Without epics, related work units become scattered:

AUTH-001: User login
AUTH-002: Password reset
AUTH-003: Session management
DASH-001: User profile display

Which ones are part of the authentication feature?
What's the overall progress?
How do prefixes relate to business initiatives?

The result: Fragmented planning, unclear priorities, lost strategic context.

How Epics Work

Epics create a hierarchical structure that connects business initiatives to implementation work:

Key Features:

Epic IDs: Lowercase-with-hyphens format (authentication-system, payment-integration)
Prefix Mapping: Link prefixes to epics for automatic association
Progress Tracking: Completion percentage and story point totals
Flexible Scope: Epics can span multiple prefixes or be prefix-specific

Epic Components

Epic ID

Format: lowercase-with-hyphens

Examples:

authentication-system
payment-integration
dashboard-redesign
performance-optimization

Validation: Enforced automatically at creation

Usage:

fspec create-epic authentication-system

Prefixes

Format: 2-6 uppercase letters

Examples:

AUTH (Authentication)
DASH (Dashboard)
API (API Layer)
PERF (Performance)

Creation and Linking:

# Create prefix and link to epic in one command
fspec create-prefix AUTH authentication-system
 
# Or link existing prefix to epic
fspec update-prefix AUTH --epic authentication-system

Progress Tracking

Progress is calculated automatically from associated work units:

Completion Percentage:

(Completed Work Units / Total Work Units) × 100

Story Points:

Completed Points / Total Points

The Two Types of Relationships

Prefix-Based Association (Automatic)

How it works: When a prefix is linked to an epic, ALL work units starting with that prefix automatically belong to the epic.

Example:

# Link AUTH prefix to epic
fspec update-prefix AUTH --epic authentication-system
 
# All these work units now belong to authentication-system epic:
# - AUTH-001
# - AUTH-002
# - AUTH-003

Advantages:

Zero manual maintenance
Consistent grouping
Clear prefix semantics

Manual Association (Explicit)

How it works: Set the epic field directly in the work unit metadata.

Example:

fspec create-story "Implement OAuth flow" \
  --epic authentication-system \
  --id OAUTH-001

When to use:

Work units that don't follow prefix conventions
Cross-cutting concerns
Legacy work units being reorganized

Natural Language Workflows

Scenario 1: Planning a New Feature

YOU: "Let's plan out the authentication system feature."

AI: I'll create an epic to organize all authentication work...
    fspec create-epic authentication-system \
      --title "User Authentication System" \
      --description "Complete authentication system including login, sessions, OAuth, and password management" \
      --tags @security @backend @high-priority

    ✓ Created epic: authentication-system

    Now I'll create a prefix for authentication work units...
    fspec create-prefix AUTH authentication-system

    ✓ Created prefix: AUTH (linked to authentication-system)

    Now any work unit starting with AUTH will automatically
    be tracked as part of the authentication-system epic.

YOU: "Add the first few stories."

AI: Creating authentication stories...
    fspec create-story "User login with email/password" --prefix AUTH --estimate 5
    fspec create-story "Password reset flow" --prefix AUTH --estimate 3
    fspec create-story "Session management" --prefix AUTH --estimate 4

    ✓ Created AUTH-001 (5 points)
    ✓ Created AUTH-002 (3 points)
    ✓ Created AUTH-003 (4 points)

    All automatically associated with authentication-system epic.
    Total: 12 story points planned

Scenario 2: Tracking Progress

YOU: "What's the status of the authentication epic?"

AI: Checking authentication-system epic progress...
    fspec show-epic authentication-system

# Epic: authentication-system
**User Authentication System**

Complete authentication system including login, sessions, OAuth, and password management

**Progress**: 60% (3/5 work units completed)
**Story Points**: 12/20 completed

## Tags
- @security
- @backend
- @high-priority

## Associated Prefixes
- AUTH

## Work Units

### ✅ Completed (3)
- AUTH-001: User login with email/password (5 points)
- AUTH-002: Password reset flow (3 points)
- AUTH-003: Session management (4 points)

### 🔄 In Progress (1)
- AUTH-004: OAuth integration (8 points)

### ⏸️ Not Started (1)
- AUTH-005: Two-factor authentication (4 points)

## Summary
We're 60% done with the authentication system. OAuth integration
is in progress, and 2FA is the only remaining work.

Scenario 3: Multi-Prefix Epic

YOU: "Create an epic for payment processing that spans multiple areas."

AI: Creating a cross-functional payment epic...
    fspec create-epic payment-integration \
      --title "Payment Processing System" \
      --description "End-to-end payment processing including checkout, billing, and invoicing"

    ✓ Created epic: payment-integration

    I'll create multiple prefixes for different aspects...
    fspec create-prefix PAY payment-integration
    fspec create-prefix BILL payment-integration
    fspec create-prefix INV payment-integration

    ✓ Created 3 prefixes linked to payment-integration

    Now you can organize work units by functional area:
    - PAY-* for payment processing
    - BILL-* for billing logic
    - INV-* for invoice generation

    All will roll up into the payment-integration epic for tracking.

Scenario 4: Reorganizing Existing Work

YOU: "Move all the API work units into a new epic."

AI: I'll create an API epic and reorganize the work...
    fspec create-epic api-modernization \
      --title "API Modernization" \
      --description "Modernize REST API to GraphQL"

    ✓ Created epic: api-modernization

    Updating the API prefix to link to this epic...
    fspec update-prefix API --epic api-modernization

    ✓ Updated prefix: API → api-modernization

    Checking how many work units were affected...
    fspec show-epic api-modernization

    ✓ Found 12 work units now associated with api-modernization
      (All work units starting with API prefix)

    The epic is now tracking all API work automatically.

Epic Creation and Management

Creating Epics

Basic creation:

fspec create-epic authentication-system

Full creation with metadata:

fspec create-epic authentication-system \
  --title "User Authentication System" \
  --description "Complete authentication including login, sessions, OAuth" \
  --tags @security @backend @high-priority

Output:

✓ Created epic: authentication-system
  Title: User Authentication System
  Tags: @security, @backend, @high-priority

Viewing Epic Details

Single epic:

fspec show-epic authentication-system

Output:

# Epic: authentication-system
**User Authentication System**
 
Complete authentication including login, sessions, OAuth
 
**Progress**: 60% (3/5 work units completed)
**Story Points**: 12/20 completed
 
## Tags
- @security
- @backend
- @high-priority
 
## Associated Prefixes
- AUTH
 
## Work Units
 
### ✅ Completed (3)
- AUTH-001: User login (5 points)
- AUTH-002: Password reset (3 points)
- AUTH-003: Sessions (4 points)
 
### 🔄 In Progress (1)
- AUTH-004: OAuth (8 points)
 
### ⏸️ Not Started (1)
- AUTH-005: 2FA (4 points)

Listing All Epics

fspec list-epics

Output:

Project Epics:

✅ authentication-system (60% complete - 12/20 points)
   User Authentication System
   Prefixes: AUTH

🔄 payment-integration (30% complete - 15/50 points)
   Payment Processing System
   Prefixes: PAY, BILL, INV

⏸️ dashboard-redesign (0% complete - 0/30 points)
   Dashboard UI Redesign
   Prefixes: DASH, UI

Total: 3 epics, 27/100 story points completed (27%)

Status indicators:

✅ = 75%+ complete
🔄 = 1-74% complete
⏸️ = 0% complete

Prefix-Epic Relationships

Creating Prefixes with Epic Link

Create and link in one command:

fspec create-prefix AUTH authentication-system

What this does:

Creates prefix AUTH with 2-6 character validation
Links it to authentication-system epic
All future AUTH-* work units auto-associate

Updating Prefix-Epic Link

Link existing prefix to epic:

fspec update-prefix AUTH --epic authentication-system

Re-link to different epic:

fspec update-prefix AUTH --epic identity-management

Remove epic link:

fspec update-prefix AUTH --epic none

Output:

✓ Updated prefix: AUTH
  Epic: authentication-system → none
  Affected work units: 5 (no longer in epic)

Viewing Prefix-Epic Mappings

fspec list-prefixes

Output:

Project Prefixes:

AUTH → authentication-system
  Description: Authentication and identity
  5 work units

DASH → dashboard-redesign
  Description: Dashboard UI components
  8 work units

API (no epic)
  Description: API endpoints
  12 work units

Progress Calculation

Progress is calculated dynamically based on current work unit states:

Completion Percentage

Formula:

(Work Units in "done" status / Total Work Units) × 100

Example:

Epic has 10 work units:
- 6 in "done" → 60% complete
- 2 in "implementing" → Active
- 2 in "backlog" → Remaining

Story Points

Formula:

Sum of estimates for "done" units / Sum of all estimates

Example:

Epic has 20 total story points:
- AUTH-001 (5 points, done)
- AUTH-002 (3 points, done)
- AUTH-003 (4 points, done)
- AUTH-004 (8 points, implementing)

Completed: 12/20 points (60%)

What if work units don't have estimates?

Units without estimates are counted in completion % but not in story points
Best practice: Estimate all work units for accurate tracking

Integration with ACDD Workflow

Epics provide strategic context throughout the ACDD lifecycle:

Planning Phase: Epic Creation

What happens:

Identify business initiative or feature set
Create epic with clear title and description
Create prefixes for categorization
Link prefixes to epic

Example dialogue:

YOU: "We need to build a payment system."

AI: I'll create an epic for payment processing...
    Epic captures the strategic goal
    Prefixes organize the tactical work
    Progress tracking connects them

Specification Phase: Work Unit Association

What happens:

Create stories/tasks/bugs with epic prefix
Automatic association via prefix
Manual association for cross-cutting work

Example:

fspec create-story "Stripe integration" --prefix PAY
→ Auto-associated with payment-integration epic

Implementation Phase: Progress Tracking

What happens:

Work units move through workflow states
Epic progress updates automatically
Story points accumulate

Example:

PAY-001 moves from implementing → done
→ Epic progress: 40% → 50%
→ Story points: 8/20 → 13/20

Completion Phase: Epic Closure

What happens:

All work units reach "done" status
Epic shows 100% completion
Retrospective on epic scope and outcomes

Decision Flow: When to Use Epics

Use epics when:

You have 3+ related work units
Work spans multiple sprints or iterations
You need progress tracking for stakeholders
Work represents a coherent business initiative

Don't use epics when:

Work is a single, isolated unit
Categorization is sufficient (use tags)
No need for progress tracking

Best Practices

✅ DO

Create epics for initiatives - Business features, major refactors, multi-sprint projects
Link prefixes to epics - Automatic association reduces manual work
Use descriptive epic IDs - authentication-system not epic-1
Add business context - Description field explains WHY the epic matters
Tag epics - @high-priority, @backend, @q1-2025 for filtering
Track progress regularly - Run fspec show-epic to monitor progress
Estimate all work units - Enables accurate story point tracking
Close epics when done - Don't leave 100% complete epics open forever

❌ DON'T

Create epics for everything - Over-organization creates overhead
Use generic epic IDs - project-1, feature-x are meaningless
Manually associate when prefix works - Use prefix-based association
Forget to update prefixes - Re-linking affects all associated work units
Mix unrelated work - Keep epic scope focused
Leave epics empty - Epics with no work units add no value

Common Patterns

Pattern 1: Feature Epic (Single Prefix)

Simple 1:1 mapping between feature and prefix:

Epic: user-notifications
  ↓
Prefix: NOTIF
  ↓
Work Units: NOTIF-001, NOTIF-002, NOTIF-003...

Use case: Self-contained features with clear boundaries

Pattern 2: Initiative Epic (Multiple Prefixes)

Complex mapping for cross-functional initiatives:

Epic: payment-integration
  ↓
Prefixes: PAY, BILL, INV
  ↓
Work Units:
  - PAY-001, PAY-002 (payment processing)
  - BILL-001, BILL-002 (billing logic)
  - INV-001 (invoice generation)

Use case: Large initiatives spanning multiple domains

Pattern 3: Milestone Epic (Mixed Association)

Combines prefix and manual association:

Epic: q1-2025-release
  ↓
Prefix: Q1
  ↓
Work Units:
  - Q1-001, Q1-002 (prefix-based)
  - AUTH-042 (manually associated)
  - PERF-015 (manually associated)

Use case: Release milestones pulling from multiple epics

Pattern 4: Refactoring Epic (Technical)

Technical improvement initiatives:

Epic: database-migration
  ↓
Prefix: DBMIG
  ↓
Work Units: DBMIG-001, DBMIG-002, DBMIG-003...

Use case: Infrastructure, performance, technical debt

Troubleshooting

Issue: Work units not associating with epic

Problem: Created work unit with prefix but doesn't show in epic

Solution:

# Verify prefix is linked to epic
fspec list-prefixes
 
# If not linked, link it
fspec update-prefix AUTH --epic authentication-system
 
# Verify work unit is now in epic
fspec show-epic authentication-system

Issue: Progress not updating

Problem: Moved work unit to done but epic progress unchanged

Solution: Epic progress updates on next query. Force refresh:

fspec show-epic epic-id

Progress is calculated on-demand, not stored.

Issue: Epic ID format rejected

Error: Epic ID must be lowercase-with-hyphens

Solution: Use valid format:

# ❌ Wrong
fspec create-epic Authentication_System
 
# ✅ Correct
fspec create-epic authentication-system

Issue: Too many epics, hard to track

Problem: Created too many epics, lost overview

Solution: Use epic tags for filtering:

# Tag epics by priority
fspec create-epic auth --tags @high-priority
fspec create-epic perf --tags @low-priority
 
# List with filtering (future feature)
fspec list-epics --tag @high-priority

Summary

Epic management provides strategic visibility across your project:

Before Epics:

Scattered work units with no grouping
Lost business context
No progress visibility
Manual tracking in spreadsheets

With Epics:

✅ Organized work by business initiative
✅ Automatic progress tracking
✅ Prefix-based categorization
✅ Story point accumulation
✅ Strategic visibility
✅ Stakeholder communication

Key Concepts:

Epic ID: lowercase-with-hyphens unique identifier
Prefixes: 2-6 uppercase letters linked to epics
Progress: Automatic calculation from work unit states
Association: Prefix-based (automatic) or manual (explicit)

Core Commands:

fspec create-epic <epic-id>                    # Create epic
fspec show-epic <epic-id>                      # View details
fspec list-epics                               # View all epics
fspec create-prefix <PREFIX> <epic-id>         # Create & link prefix
fspec update-prefix <PREFIX> --epic <epic-id>  # Update prefix link

Integration Points:

Planning: Epic creation defines scope
Specification: Work units auto-associate via prefix
Implementation: Progress updates automatically
Validation: Epic completion tracking
Reporting: Stakeholder visibility

Epics transform scattered work into strategic initiatives with clear goals, progress tracking, and business context.

Foundation Document Review Command