Add Epic

Add Epic

Context

You are adding a new epic to an existing development plan. This is useful when scope expands or new feature areas are identified after initial planning.

Current Plan

Read the file docs/development-plan.md to get the current plan contents. If the file doesn't exist, inform the user and suggest running /vk:create-plan first.

Instructions

1. Gather Epic Information

If the user didn't provide all details inline, use AskUserQuestion for the structured fields and plain text prompts for the open-ended ones.

Use AskUserQuestion for:

• Question: "Where should this epic be inserted?"

  • Header: "Position"
  • Options: Populate dynamically from existing epics (e.g., "After Epic 1: Foundation" / "After Epic 2: Core Features" / "Append at end (Recommended)"). Use the current plan's epic list.

• Question: "What priority level for this epic?"

  • Header: "Priority"
  • Options: High — description: Critical path, do next / Medium — description: Important but not blocking / Low — description: Nice to have, can wait

Ask as plain text (these are too open-ended for structured options):

• Epic name - Clear, descriptive name for the epic
• Description - Brief description of what this epic covers
• Tasks - List of tasks to include (can be added later)

2. Determine Epic Number

Based on existing epics:

• If inserting between existing epics, renumber subsequent epics
• If appending, use next available number
• Update all task IDs accordingly if renumbering

3. Create Epic Structure

Format the new epic:

---

## Epic [N]: [Epic Name] (NOT STARTED)

[Description of what this epic covers and why it was added]

### Acceptance Criteria

- [ ] [Criterion 1]
- [ ] [Criterion 2]

### Tasks

| ID | Title | Description | Priority | Complexity | Depends On | Status |
|----|-------|-------------|----------|------------|------------|--------|
| N.1 | [Task title] | [Description] | High | S | — | <!-- vk: --> |
| N.2 | [Task title] | [Description] | Medium | M | N.1 | <!-- vk: --> |

---

4. Update the Plan

1. Insert the new epic at the appropriate location
2. Update the Completion Status Summary table to include the new epic
3. Renumber subsequent epics if inserting (not appending)
4. Update task IDs for any renumbered epics
5. Add changelog entry in docs/development-plan-changelog.md

5. Update Summary Table

Add the new epic to the summary:

| [N]. [Epic Name] | Not Started | 0% |

6. Changelog Entry

Add to docs/development-plan-changelog.md (prepend at the top of the list):

- **[date]**: Added Epic [N]: [Epic Name] - [brief reason for addition]

Example

User request: "Add a new epic for API documentation between Epic 2 and Epic 3"

Before:

## Completion Status Summary

| Epic | Status | Progress |
|------|--------|----------|
| 1. Foundation | Complete | 100% |
| 2. Core Features | In Progress | 50% |
| 3. Polish | Not Started | 0% |

After:

## Completion Status Summary

| Epic | Status | Progress |
|------|--------|----------|
| 1. Foundation | Complete | 100% |
| 2. Core Features | In Progress | 50% |
| 3. API Documentation | Not Started | 0% |
| 4. Polish | Not Started | 0% |

Note: Epic 3 (Polish) became Epic 4, and all its task IDs changed from 3.x to 4.x.

Output

After adding the epic:

1. Confirm the addition - Show the new epic structure
2. Show updated summary table - Display the new completion status summary
3. List renumbered items - If any epics/tasks were renumbered, list them
4. Next steps - Remind user to:
   • Add more tasks with /vk:add-epic or by editing the plan directly
   • Run /vk:generate-tasks to create VK tasks for the new epic
   • Review the epic's acceptance criteria

Handling Task Renumbering

If inserting an epic causes renumbering:

1. Update all task IDs in affected epics (e.g., 3.1 → 4.1)
2. If tasks were already linked to VK, their VK IDs remain the same
3. Update the task titles in VK to reflect new IDs (optional but recommended)
4. Note the renumbering in docs/development-plan-changelog.md

- **[date]**: Added Epic 3: API Documentation; renumbered Epic 3 (Polish) to Epic 4