new-epic

Creates an epic.html planning document with direction, guard rails, and a sequenced task breakdown.

Updated Apr 17, 2026
One-click install
npx skills add https://github.com/mistakenot/skills --skill new-epic-mistakenot
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: new-epic
Source: https://github.com/mistakenot/skills/tree/main/plugins/planning-workflow/skills/new-epic
Command: npx skills add https://github.com/mistakenot/skills --skill new-epic-mistakenot

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Large initiatives spanning multiple tasks lack a shared source of direction, causing task planners to make inconsistent decisions and defer integration risk. This Skill produces a single epic document that sets user-facing direction, cross-task guard rails, and a deployable task breakdown before any task is planned. ## Core Features & Use Cases - Epic document authoring: Creates docs/epics/epic-$ID-$NAME.html with auto-assigned sequential IDs, pd-meta lifecycle fields, and tabbed sections for vision, guard rails, architecture seams, breakdown, and decisions. - Vertical-slice decomposition: Breaks the initiative into independently deployable, sequenced tasks with a walking-skeleton first task that runs end to end through every layer. - Open-question gating: Surfaces direction-setting assumptions as <pd-question> entries with recommended answers when running autonomously, or asks the user interactively. - Use Case: You are starting a multi-week partner API program. Run the skill to produce an epic that states the user-facing outcome, the guard rails every task inherits, and a five-task breakdown, then plan each task individually with /new-task. ## Quick Start Ask the agent to create a new epic for your initiative, for example: plan an epic for the partner API program.

Frequently Asked Questions about new-epic

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I plan an epic that spans multiple tasks?▼

Invoke the new-epic skill with your initiative description. It scans existing docs/epics files, assigns the next sequential ID, and creates an epic HTML document with vision, guard rails, architecture seams, and a deployable task breakdown.

What is the difference between an epic and a task in this workflow?▼

An epic sets direction and constraints at a high altitude: user outcomes, guard rails, and seams, with no files or code. A task, planned with new-task, handles construction detail for one deployable slice within the epic's boundaries.

When should I use new-task instead of new-epic?▼

Use new-task when the work is a single deployable change. The epic skill explicitly pushes back if the initiative is only one task, or if it is so large it should be split into several epics.

How does the epic breakdown avoid integration risk?▼

It decomposes work into vertical slices rather than layers. Task 1 is a walking skeleton touching every layer end to end, and later tasks thicken it, so integration is verified early instead of deferred to the end.

What happens to unresolved questions when running autonomously?▼

Each genuine direction-setting decision is recorded as a pd-question element with a recommended answer. This gates the epic so task planning cannot start on unset direction, while a human can approve with one click.