Top-level feature directories

The user input to you can be provided directly by the agent or as a command argument - you MUST consider it before proceeding with the prompt (if not empty).

User input:

$ARGUMENTS

⚠️ Step 0: Read Template First

Before any other action — read this template now using the Read tool:

.speck/​templates/​epic/​epic-template.md

The template defines required sections and formatting for epic.md. Reading it first shapes what you look for when scanning the codebase — you'll know what information each epic document needs to contain.

Checkpoint: After reading, note the top-level sections from the template. Then continue to Step 1.

Discover epic boundaries from existing code and documentation.

Context Requirements

First, establish project context:

• If project specified in arguments, use it
• Otherwise ask: "Which project should I discover epics for?"
• Load project.md and any import report

Verify project has:

• Existing codebase path or
• Documentation to analyze or
• Previous import analysis

Step 1: Analysis Preparation

Determine Analysis Scope

Ask if not clear:

• "Should I analyze the entire codebase or specific areas?"
• "Any particular features you want me to focus on?"
• "Are there existing epic boundaries I should respect?"

Load Previous Analysis

If project was imported:

• Load import report
• Review epic candidates
• Note confidence levels

Step 2: Deep Code Analysis

Structural Analysis

Examine code organization:

# Top-level feature directories
find [PROJECT_PATH] -type d -mindepth 1 -maxdepth 2 | grep -E "(feature|module|domain|service|component)s?" | sort

# Route/​endpoint analysis
grep -r "router\|route\|endpoint\|path\|api/" [PROJECT_PATH] --include="*.{js,ts,py,java,go}" | grep -v node_modules | head -20

# Database schema indicators
find [PROJECT_PATH] -name "*.sql" -o -name "*migration*" -o -name "*schema*" | head -20

# Service boundaries
grep -r "class.*Service\|function.*Service" [PROJECT_PATH] --include="*.{js,ts,py,java,go}" | head -20

Semantic Analysis

Look for business capabilities:

Authentication Patterns:

auth, login, logout, session, token, oauth, sso, 
password, credential, permission, role, access

User Management Patterns:

user, profile, account, settings, preferences,
registration, onboarding, avatar, notification

Data Management Patterns:

create, read, update, delete, list, search,
filter, sort, paginate, export, import

Dependency Analysis

Trace connections between code areas:

• Import/​require statements
• Database foreign keys
• API call patterns
• Shared utilities

Step 3: Epic Boundary Definition

Epic Candidate Evaluation

For each potential epic, assess:

Cohesion Score (1-10):

• Files work together: +3
• Shared data model: +2
• Common user goal: +3
• Single team ownership: +2

Independence Score (1-10):

• Few external dependencies: +3
• Clear API boundaries: +3
• Separate database tables: +2
• Independent deployment: +2

Value Score (1-10):

• Delivers user value alone: +4
• Clear success metrics: +3
• Business priority: +3

Epic Sizing

Estimate story count by analyzing:

• Number of endpoints/​routes
• Distinct UI components
• Database operations
• Business rules complexity

Size guidelines:

• 3-5 stories: Small epic
• 6-12 stories: Medium epic
• 13-20 stories: Large epic

• 20 stories: Consider splitting

Step 4: Generate Epic Specifications

For each discovered epic:

Create Epic Structure

mkdir -p specs/​projects/[PROJECT_ID]/​epics/[EPIC_ID]-[epic-name]

Generate Epic Spec

This command does NOT have its own output template. Generate/​update canonical Speck artifacts using existing templates:

Generate epic.md (WHAT/​WHY + boundaries)

• Load and follow the template exactly: .speck/​templates/​epic/​epic-template.md
• Populate from code-derived behavior + docs
• If you need to preserve code evidence, add a brief [FROM SCAN] note under Information Sources in epic.md (e.g., top-level paths/​keywords analyzed)
• Do not paste deep technical inventories (endpoints/​models/​files) into epic.md — those belong in epic-codebase-scan.md generated by /​epic-scan
• Mark uncertain items as: [NEEDS CLARIFICATION: ...]

Traceability markers:

• Use [FROM SCAN] for statements grounded in code scan results
• Use [INFERRED] for inferences not directly verified

Step 5: Cross-Epic Analysis

Dependency Map

Create visual representation:

Authentication Epic
    ↓ provides sessions to
User Management Epic
    ↓ provides users to
Content Management Epic
    ↓ provides content to
Analytics Epic

Overlap Detection

Identify shared concerns:

• Shared files between epics
• Duplicate functionality
• Unclear boundaries

Recommended Epic Order

Based on dependencies:

1. [Epic] - No dependencies
2. [Epic] - Depends on #1
3. [Epic] - Depends on #1, #2

Step 6: Discovery Report

Return a discovery summary as command output (do not introduce a new “report template” doc).

Include:

• Epics discovered (name, size, estimated stories, confidence)
• Key dependency relationships + recommended order
• Coverage gaps / unclear boundaries
• Recommendations + next commands (/​epic-specify, /​story-extract, /​project-plan, etc.)

Step 7: Interactive Refinement

Present findings:

• "I've discovered [N] potential epics. Here's what I found..."
• "These boundaries make sense based on your code structure"
• "I'm less certain about [epic] - can you clarify?"

Get feedback:

• "Do these epic boundaries align with your team structure?"
• "Are there business boundaries I missed?"
• "Should any of these be combined or split?"

Step 8: Guide Next Steps

Based on discovery:

• Many small epics → "Consider combining related ones"
• Few large epics → "Consider splitting by user journey"
• Clear boundaries → "Ready to extract stories"
• Unclear code → "Need team input on organization"

Recommend:

• /​epic-clarify - Confirm/​adjust scope + resolve [NEEDS CLARIFICATION] items
• /​epic-scan - Generate/​update epic-codebase-scan.md (domain evidence + reusable patterns) before planning
• /​story-extract - Extract stories from code
• /​epic-plan - Create tech specs
• "Review with team for validation"

Discovery Patterns

Well-Structured Codebases

• Trust directory structure
• Epics align with top-level directories
• High confidence in boundaries

Domain-Driven Codebases

• Epics align with bounded contexts
• Look for aggregates and entities
• Focus on business capabilities

Legacy Codebases

• Ignore file organization
• Focus on user capabilities
• Plan refactoring within epics

Microservices

• Services often = epics
• Check for service boundaries
• Consider cross-service epics

Success Criteria

Successful epic discovery:

• ✅ All major features covered
• ✅ Clear boundaries defined
• ✅ Dependencies mapped
• ✅ Sizing seems reasonable
• ✅ Team agrees with structure