epic-management

What this skill does

# Epic Management

## Overview

An **epic** groups related issues that together deliver a feature or capability. This skill creates, tracks, and manages epics using GitHub's native features.

**Core principle:** An epic is a collection of issues that together deliver user value.

**Announce at start:** "I'm using epic-management to structure this feature into a tracked epic with related issues."

## What is an Epic?

An epic is:
- A parent issue with the `epic` label
- A collection of related issues sharing an `epic-[name]` label
- Optionally associated with a milestone
- Part of an initiative (if the work is massive)

## Epic Structure in GitHub

```
Epic (Parent Issue)
├── Label: epic
├── Label: epic-[name]
├── Milestone: [optional]
└── Project: [with epic fields]

Related Issues
├── Label: epic-[name]
├── Reference: "Part of #[EPIC_NUMBER]"
└── Milestone: [same as epic]
```

## Creating an Epic

### Step 1: Create Epic Label

```bash
# Create the epic-specific label
gh label create "epic-[SHORT-NAME]" \
  --color "0E8A16" \
  --description "[Brief description of epic goal]"
```

### Step 2: Create Epic Tracking Issue

```bash
gh issue create \
  --title "[Epic] [NAME]" \
  --label "epic,epic-[SHORT-NAME]" \
  --body "## Epic: [NAME]

## Goal
[What this epic delivers when complete]

## Success Criteria
- [ ] [High-level criterion 1]
- [ ] [High-level criterion 2]
- [ ] [High-level criterion 3]

## Context
[Background, why this epic exists, any relevant links]

## Dependencies
- **Requires:** [Other epics/issues that must complete first]
- **Enables:** [Other epics/issues that depend on this]

## Issues

### Ready
- [ ] #[N] - [Title]

### In Progress
[None yet]

### Done
[None yet]

## Progress
**Issues:** 0 / [TOTAL] complete
**Last Updated:** [DATE]

---
## Initiative
[Part of #[INITIATIVE] if applicable, or 'Standalone epic']

## Milestone
[Associated milestone or 'Not assigned']"
```

### Step 3: Add to Project Board (MANDATORY GATE)

**This step is NOT optional. Epics MUST be in the project board.**

```bash
# Get the epic issue URL
EPIC_URL=$(gh issue view [EPIC_NUMBER] --json url -q '.url')

# Add epic to project - REQUIRED
gh project item-add "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --url "$EPIC_URL"

if [ $? -ne 0 ]; then
  echo "ERROR: Failed to add epic to project. Cannot proceed."
  exit 1
fi

# Get the item ID - REQUIRED
ITEM_ID=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r ".items[] | select(.content.number == [EPIC_NUMBER]) | .id")

if [ -z "$ITEM_ID" ] || [ "$ITEM_ID" = "null" ]; then
  echo "ERROR: Epic added but item ID not found."
  exit 1
fi

echo "Epic #[EPIC_NUMBER] added to project with item ID: $ITEM_ID"
```

### Step 3.5: Set Project Board Fields (MANDATORY)

**All epics must have Type = Epic set in project board.**

```bash
# Get project and field IDs
PROJECT_ID=$(gh project list --owner "$GH_PROJECT_OWNER" --format json | \
  jq -r ".projects[] | select(.number == $GITHUB_PROJECT_NUM) | .id")

STATUS_FIELD_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Status") | .id')

TYPE_FIELD_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Type") | .id')

# Get option IDs
BACKLOG_OPTION_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Status") | .options[] | select(.name == "Backlog") | .id')

EPIC_TYPE_OPTION_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Type") | .options[] | select(.name == "Epic") | .id')

# Set Status = Backlog (or Ready if no issues yet to create)
gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
  --field-id "$STATUS_FIELD_ID" --single-select-option-id "$BACKLOG_OPTION_ID"

# Set Type = Epic
gh project item-edit --project-id "$PROJECT_ID" --id "$ITEM_ID" \
  --field-id "$TYPE_FIELD_ID" --single-select-option-id "$EPIC_TYPE_OPTION_ID"

# Verify fields were set
echo "Verifying project board fields..."
VERIFY=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq ".items[] | select(.content.number == [EPIC_NUMBER])")

echo "Status: $(echo "$VERIFY" | jq -r '.status.name')"
echo "Type: $(echo "$VERIFY" | jq -r '.type.name // "not set"')"
```

**Skill:** `project-board-enforcement`

## Creating Issues Within an Epic

### Issue Template for Epic Issues

```bash
gh issue create \
  --title "[TYPE] [Title]" \
  --label "epic-[SHORT-NAME]" \
  --body "## Description
[What this issue delivers]

Part of epic #[EPIC_NUMBER]: [Epic Title]

## Acceptance Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]

## Technical Notes
[Any implementation details]

## Dependencies
- Requires: #[N] (if any)
- Blocks: #[N] (if any)"
```

### Linking Issues to Epic

Every issue in an epic must:
1. Have the `epic-[name]` label
2. Reference the epic in description: "Part of epic #[N]"
3. Share the same milestone (if set)
4. **Be in the project board with Status and Type set**
5. **Have Epic field set to parent epic number (if field exists)**

### Adding Child Issues to Project Board (MANDATORY)

```bash
# After creating child issue, add to project board
CHILD_URL=$(gh issue view [CHILD_NUMBER] --json url -q '.url')

gh project item-add "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" --url "$CHILD_URL"

# Get item ID
CHILD_ITEM_ID=$(gh project item-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r ".items[] | select(.content.number == [CHILD_NUMBER]) | .id")

# Set Status = Ready
gh project item-edit --project-id "$PROJECT_ID" --id "$CHILD_ITEM_ID" \
  --field-id "$STATUS_FIELD_ID" --single-select-option-id "$READY_OPTION_ID"

# Set Type (Feature, Bug, etc. as appropriate)
gh project item-edit --project-id "$PROJECT_ID" --id "$CHILD_ITEM_ID" \
  --field-id "$TYPE_FIELD_ID" --single-select-option-id "$TYPE_OPTION_ID"

# Link to parent epic (if Epic field exists)
EPIC_FIELD_ID=$(gh project field-list "$GITHUB_PROJECT_NUM" --owner "$GH_PROJECT_OWNER" \
  --format json | jq -r '.fields[] | select(.name == "Epic") | .id')

if [ -n "$EPIC_FIELD_ID" ] && [ "$EPIC_FIELD_ID" != "null" ]; then
  gh project item-edit --project-id "$PROJECT_ID" --id "$CHILD_ITEM_ID" \
    --field-id "$EPIC_FIELD_ID" --text "#[EPIC_NUMBER]"
fi
```

**Skill:** `project-board-enforcement`

## Tracking Epic Progress

### Update Epic Issue Regularly

When issues change status, update the epic:

```bash
gh issue comment [EPIC_NUMBER] --body "## Progress Update - [DATE]

**Completed:** #[N] - [Title]

**Current Status:**
- Ready: [X] issues
- In Progress: [Y] issues
- Done: [Z] issues
- Total: [X+Y+Z] / [TOTAL]

**Next up:** #[N] - [Title]"
```

### Reorganize Epic Body

Keep the epic body current:

```markdown
## Issues

### Ready
- [ ] #102 - Database schema
- [ ] #103 - API endpoints

### In Progress
- [ ] #101 - Initial setup (assignee: @dev)

### Done
- [x] #100 - Research spike

## Progress
**Issues:** 1 / 4 complete (25%)
**Last Updated:** 2025-12-02
```

## Epic Lifecycle

```
┌────────────┐     ┌────────────┐     ┌────────────┐     ┌────────────┐
│  Planning  │────▶│   Active   │────▶│  Closing   │────▶│   Done     │
└────────────┘     └────────────┘     └────────────┘     └────────────┘
     │                   │                   │                  │
     ▼                   ▼                   ▼                  ▼
  Creating            Issues              Last issues       All issues
  issues              in progress         completing        closed
```

### Epic States

| State | Project Status | Indicators |
|-------|----------------|------------|
| Planning | Backlog | Issues being created, no work started |
| Active | In Progress | At least one issue in progress |
| Closing |