# Epic Naming Convention Standard

**Date**: 2025-10-29 | **Status**: ENFORCED | **Version**: 1.0

## Epic Naming Rule

All epics must follow this pattern:

### Title Format
```
[Epic] Brief description of the epic work
```

**Key Rules:**
- Start with `[Epic]` (no number in the title)
- Followed by a brief, descriptive title
- Example: `[Epic] Phase 2A: Refactor IMPLEMENT Commands`
- **NOT**: `[Epic 366] Phase 2A...` ❌

### Label Format

Every epic must have these labels:

```
Labels:
  - enhancement        (type)
  - epic              (required for all epics)
  - epic-[NUMBER]     (matches the issue number)
  - [optional additional labels]
```

**Required Labels:**
1. `enhancement` - Issue type
2. `epic` - Marks as epic (allows issue linking in GitHub projects)
3. `epic-[NUMBER]` - Label with exact issue number (e.g., `epic-366`)

**Optional Labels:**
- `phase-2` - Development phase
- `high-priority` - Priority indicator
- Other project-specific tags

### Examples

**Epic #360** (Correct ✅)
- Title: `[Epic] Scripts Folder Organization & Consolidation`
- Labels: `enhancement`, `epic`, `epic-360`

**Epic #366** (Now Correct ✅)
- Title: `[Epic] Phase 2A: Refactor IMPLEMENT Commands to Use Orchestrators`
- Labels: `enhancement`, `epic`, `phase-2`, `epic-366`

**Epic #367** (Now Correct ✅)
- Title: `[Epic] Phase 2B: Consolidate Duplicate Utility Modules`
- Labels: `enhancement`, `epic`, `phase-2`, `epic-367`, `high-priority`

## Why This Convention?

### Benefits

1. **Consistency** - All epics follow same pattern
2. **GitHub Projects** - `epic` label enables issue linking
3. **Issue Tracking** - `epic-[NUMBER]` label links children to parent
4. **Clarity** - No confusion about issue type or number
5. **Automation** - Scripts can reliably find epics by label

### Epic Label Linking

The `epic-[NUMBER]` label is crucial for:
- Grouping child issues to parent epic
- Automated issue closure workflows
- Release tracking and status updates
- Dependency analysis

## Creating New Epics

### Template

When creating a new epic, use this template:

```
Title: [Epic] [Phase]: [Brief Description]

Example:
Title: [Epic] Phase 3: Implement Consolidation

Labels:
- enhancement
- epic
- epic-[ISSUE_NUMBER]    ← CRITICAL: matches issue number
- [any other relevant labels]
```

### Checklist

- [ ] Title starts with `[Epic]`
- [ ] No number in title
- [ ] Has `enhancement` label
- [ ] Has `epic` label
- [ ] Has `epic-[NUMBER]` label matching issue number
- [ ] Number in label matches actual issue number (NOT sequential count)

## Common Mistakes to Avoid

❌ **WRONG** Examples:

```
Title: [Epic 366] Phase 2A: Refactor Commands
           ↑ Issue number in title - WRONG

Title: Epic: Phase 2A Refactor Commands
       ↑ Missing brackets - WRONG

Title: [Epic] Phase 2A: Refactor Commands
Labels: epic-361    ← Wrong number! Should be epic-366
           ↑

Labels: epic        ← Missing the number!
```

✅ **CORRECT** Examples:

```
Title: [Epic] Phase 2A: Refactor IMPLEMENT Commands
       ↑ No number, brackets only

Labels: 
  - enhancement
  - epic
  - epic-366        ← Exact issue number
  - phase-2
```

## How to Apply to Existing Epics

If an epic was created with wrong naming:

```bash
# Update title (remove number)
gh issue edit #ISSUE_NUMBER \
  --title "[Epic] Phase X: Description"

# Update labels (fix epic-[NUMBER])
gh issue edit #ISSUE_NUMBER \
  --set-labels enhancement,epic,epic-ISSUE_NUMBER
```

## Reference Implementation

From automation scripts that create epics:

```javascript
const createEpic = (title, description) => {
  return {
    title: `[Epic] ${title}`,  // Always prefix with [Epic]
    body: description,
    labels: [
      'enhancement',
      'epic',
      `epic-${issueNumber}`    // Use actual issue number
    ]
  };
};
```

## Validation Script

To validate epic naming across the repository:

```bash
# Find all epics
gh issue list --label epic --json number,title,labels

# Check each one:
# ✅ Title starts with "[Epic] "
# ✅ No number in title
# ✅ Has "epic" label
# ✅ Has "epic-[NUMBER]" label matching issue number
```

## Status Update

### Fixed Epics (2025-10-29)

| Epic | Before | After | Status |
|------|--------|-------|--------|
| #360 | [Epic 357] | [Epic] | ✅ FIXED |
| #366 | [Epic 361] | [Epic] | ✅ FIXED |
| #367 | [Epic 362] | [Epic] | ✅ FIXED |

### Going Forward

All future epics created via automation will follow this pattern automatically.

---

**Standard**: Epic Naming Convention v1.0  
**Last Updated**: 2025-10-29  
**Enforced**: Immediately for all new epics  
**Validation**: Automated checks recommended