Epic Decomposition

Epic Issue → Planning → Subtasks → Sequential Execution → Completion

# Epic Examples
 
## Multi-component Tasks
"Add user authentication with OAuth, JWT tokens, and profile management"
 
## Infrastructure Changes
"Set up CI/CD pipeline with Docker, tests, and deployment automation"
 
## Feature Workflows
"Implement complete order processing: cart → checkout → payment → fulfillment"

# ~/.pilot/config.yaml
orchestrator:
  execution:
    decompose:
      enabled: true           # Enable epic decomposition
      min_complexity: "epic"  # Only epics are decomposed
      max_subtasks: 5         # Limit subtask count
      min_description_words: 100  # Word threshold for decomposition

You are a software architect planning an implementation.

Break down this epic task into 3-5 sequential subtasks that can
each be completed independently. Each subtask should be a concrete,
implementable unit of work.

## CRITICAL: Avoid Single-Package Splits
If all work lives in one package or directory (e.g., all files in `cmd/pilot/`),
DO NOT split into separate subtasks. Instead, return a SINGLE subtask with
the full scope.

## Task to Plan
**Title:** Add user authentication system
**Description:** [Epic description here]

## Output Format
1. **Setup authentication infrastructure** - Database models and middleware
2. **Implement OAuth flow** - Google/GitHub OAuth integration
3. **Add JWT token management** - Token generation and validation
4. **Build user profile pages** - Profile CRUD operations
5. **Add authentication tests** - Unit and integration test coverage

// Smart conflict detection
func isSinglePackageScope(subtasks []PlannedSubtask) bool {
    dirs := extractUniqueDirectories(allSubtaskText)
 
    // If all subtasks touch the same directory → execute as one task
    if len(dirs) == 1 {
        return true // Skip decomposition
    }
 
    return false
}

# Parent epic (not executed directly)
pilot/GH-123  # Epic issue branch (unused)
 
# Subtask branches (executed sequentially)
pilot/GH-124  # Subtask 1: Setup infrastructure
pilot/GH-125  # Subtask 2: OAuth implementation
pilot/GH-126  # Subtask 3: JWT management
pilot/GH-127  # Subtask 4: Profile pages
pilot/GH-128  # Subtask 5: Test coverage

Subtask 1 → PR Created → CI Passes → Merged
             ↓
Subtask 2 → PR Created → CI Passes → Merged
             ↓
Subtask 3 → PR Created → CI Passes → Merged
             ↓
... continues until all subtasks complete

⏳ Progress: 2/5 - Starting: **JWT token management** (#126)

✅ Completed: 5/5 sub-issues done
 
All sub-tasks executed successfully.

# Each subtask PR is tracked independently
autopilot:
  enabled: true
  environment: stage
  merge_delay: 5m  # Applied to each subtask PR

// Register sub-issue PR with autopilot (GH-596)
if result.PRUrl != "" && r.onSubIssuePRCreated != nil {
    prNum := parsePRNumberFromURL(result.PRUrl)
    r.onSubIssuePRCreated(prNum, result.PRUrl, issue.Number,
                         result.CommitSHA, subTask.Branch)
}

## Epic: User Authentication System
 
### Overview
Implement complete user authentication with OAuth providers,
JWT tokens, and profile management.
 
### Requirements
- [ ] OAuth integration (Google, GitHub)
- [ ] JWT token generation and validation
- [ ] User profile CRUD operations
- [ ] Role-based access control
- [ ] Comprehensive test coverage
 
### Technical Approach
- Database: PostgreSQL with user/session tables
- Auth: OAuth 2.0 + JWT tokens
- Frontend: React components for login/profile
- Backend: Express middleware for auth checks
 
### Acceptance Criteria
- [ ] Users can login with OAuth
- [ ] JWT tokens expire and refresh properly
- [ ] Profile pages allow editing user info
- [ ] Tests cover all auth flows
- [ ] Documentation updated

# ❌ Bad Epic (single package scope)
"Refactor cmd/pilot/main.go to add configuration loading"
 
# ✅ Good Epic (multiple components)
"Add configuration system with YAML files, env vars, and validation"

# Add no-decompose label to skip epic planning
gh issue create \
  --title "Complex but monolithic task" \
  --label "pilot,no-decompose" \
  --body "This should execute as one task"

// Plan an epic into subtasks
func (r *Runner) PlanEpic(ctx context.Context, task *Task,
                         executionPath string) (*EpicPlan, error)
 
// Create GitHub issues from planned subtasks
func (r *Runner) CreateSubIssues(ctx context.Context, plan *EpicPlan,
                                executionPath string) ([]CreatedIssue, error)
 
// Execute subtasks sequentially with progress tracking
func (r *Runner) ExecuteSubIssues(ctx context.Context, parent *Task,
                                 issues []CreatedIssue,
                                 executionPath string) error

type EpicPlan struct {
    ParentTask  *Task              // Original epic task
    Subtasks    []PlannedSubtask   // Planned subtasks (3-5)
    TotalEffort string             // Effort estimate
    PlanOutput  string             // Raw Claude output
}
 
type PlannedSubtask struct {
    Title       string    // Short subtask title
    Description string    // Detailed description
    Order       int       // Execution order (1-indexed)
    DependsOn   []int     // Dependency orders
}
 
type CreatedIssue struct {
    Number      int              // GitHub issue number
    URL         string           // Issue URL
    Subtask     PlannedSubtask   // Associated planned subtask
}

Traditional Epic Execution:
- 1 large Claude Code session: ~50K tokens
- 1 massive PR review cycle
- High risk of conflicts/revisions

Epic Decomposition:
- 1 planning call: ~5K tokens
- 5 focused executions: 5 × ~15K = ~75K tokens
- Total: ~80K tokens (60% increase)
- BUT: Higher success rate, less rework, parallel execution

Execution Killed → DecomposeForRetry → Subtask Issues → Sequential Retry

# ~/.pilot/config.yaml
retry:
  decompose_on_kill: true  # Opt-in: retry killed executions via decomposition

// internal/executor/decompose.go
// Check description length — only enforce in heuristic mode (GH-1728).
// When the LLM classifier is attached and confirmed COMPLEX, trust it over word count.
wordCount := len(strings.Fields(task.Description))
usedLLMClassifier := d.classifier != nil
if !usedLLMClassifier && wordCount < d.config.MinDescriptionWords {
    return &DecomposeResult{
        Decomposed: false,
        Reason:     "description too short for decomposition (heuristic mode)",
    }
}

Sub-issue PR Merged → Check Siblings → All Closed? → Close Parent

Parent: GH-123
 
Implement OAuth flow for Google and GitHub providers...

repo:{owner}/{repo} "Parent: GH-{parentNum}" is:issue is:open