| name | create-epic |
| description | Captures a discussed multi-phase workstream as an Epic Spec work item ready for /do. For a single-outcome change use /create-feature instead. |
| argument-hint | [epic title or one-line summary] |
| disable-model-invocation | true |
Create Epic
Epic: $ARGUMENTS
Turn what the conversation has established (typically a /discussion) into an Epic
Spec that /do can execute phase by phase. The completion artifact is
./tmp/<id>/item.md with status: ready. Epics run sequentially in one PR —
phase n+1 starts only after phase n's channel completes.
This skill captures and sharpens — it does not re-run the discussion.
Steps
1. Assemble the core from the conversation
Drive toward what the spec needs, pulling from the discussion so far:
- Problem / context — the broader problem and why now
- Goals and desired end state — what the world looks like when the epic lands
- Locked directions — only decisions the model shouldn't re-make (number them D1, D2…)
- Out of scope
Where the conversation left a gap, ask the user directly — one focused round. If a
codebase fact is missing, dispatch the codex skill (role code-researcher); for an
external fact, the web-researcher sub-agent.
Success criteria: the user has explicitly agreed to problem, end state, each locked
direction, and the out-of-scope list.
2. Cut the phases
Split the work into sequential phases, each a self-contained work item: one coherent
outcome, independently verifiable, buildable on the phases before it. Don't split
because many files are touched — split where verification surfaces genuinely differ.
If it collapses to one phase, say so and suggest /create-feature instead.
Success criteria: phase table agreed with the user — each phase has a goal, scope,
and its own verification surface; order confirmed.
3. Write the work item
Draft ./tmp/<id>/item.md per ~/.references/draft-work-item.md, using this
skill's references/epic-spec.md as the template. Epic specifics:
- Verification criteria are per phase:
AC1… numbered within each phase,
each mapped to a method matched to that phase's change type.
- Keep spec altitude: no file lists, pseudo-code, or task sequences —
/do's plan stage owns the how per phase.
Success criteria: item.md exists; phases are sequential and independently
verifiable; every AC is numbered, observable, and mapped; spec altitude respected.
4. Socratic gate
Run the gate per ~/.references/socratic-gate.md. A multi-phase commitment
is never "straightforward" — expect the full challenge. For an epic it bears
down on shape (are the phases real?), appetite, consequences, and
completeness, alongside necessity and assumptions. If the dialogue collapses
the epic to one phase, hand off to /create-feature.
Success criteria: gate procedure complete — socrates returned pass (or
the cap was reached, or the user waived); ## Justification written into
item.md.
5. Mark ready and publish
Publish per ~/.references/publish-work-item.md — issue title
feat: <epic title>, issue body = the epic's problem, end state, the
phases table, and the Justification section.
Success criteria: published and cross-linked per the shared procedure.
Suggested next steps:
- `/do <issue # or ./tmp/<id>/item.md>` — run the pipeline; phases execute sequentially, one PR
- `/discussion [follow-up]` — if a phase boundary needs more thinking first
