epic-create

Epic create

Overview

epic-create is the outer, orchestrating workflow for non-trivial work. It runs the brainstorm → design → plan pipeline, creates the finite epic in its resolved home (the org .github by default; a private repo self-homes its epics — see Preflight), seeds the epic's bookend tasks, and publishes the spec and plan as the epic's docs. This is where significant work starts — not a step reached at the end.

Canonical convention: vergil-project/.github#40; worked example (this skill's own redesign): vergil-project/.github#85.

Default entry point

Start here, not in brainstorming. A solution worth thinking through is worth recording as work, so there is little value in brainstorming a design and then walking away from it untracked. epic-create opens into brainstorming and lets the process play out.

• Most work at this scale is a significant feature or change → an epic.
• If the design collapses to a trivial, single-PR change → it is a task, not an epic. File it in the member repo under an existing finite epic or the repo's ad-hoc epic (vrg-issue-create --epic adhoc) and stop. Do not mint an epic.

When unsure, it is a task. Epics are for initiatives, not individual changes.

The epic architecture — bookend tasks

An epic is never closed until you have decided what comes next AND confirmed the docs reflect what changed. Almost no real problem is 100% closed by one epic; you deliver a tangible subset and acknowledge the follow-on. So every epic carries these bookend tasks:

• First task — documentation. The spec + plan for the epic; this task's PR publishes them into .github (see the workflow below).
• Closing bookends — ordered, both mandatory:
  1. Documentation-review task — verify the epic's changes are comprehensively reflected in the human-facing docs, especially the versioned site docs (docs/site/…), which are the primary interface for understanding the system and tend to drift behind the code. Treat this as a sweep, not a single edit: an epic's documentation usually spans multiple repositories — per-repo docs in each member repo, the higher-level summary docs in the docs repo, and occasionally correction/plan notes in .github. So it does not assume one docs PR closes it. Where a repo's docs need work, the review spawns a per-repo doc task (born linked under the epic), each closed by a same-repo PR — the only linkage that respects the placement law (see Notes). File the review task itself in the repo where the bulk of its own sweep lands (usually the member repo holding the site docs, e.g. vergil-tooling/docs/site); it spawns siblings for the other repos rather than forcing one cross-repo PR to close it. It runs before the retrospective.
  2. Retrospective task (terminal) — the mandatory, single, backward-looking record that partners the spec and plan at the documentation tier; a later reader follows spec → plan → retrospective. Authored with epic-retrospective, the run-once finishing skill whose preflight gate refuses to run until every other child of the epic is closed. Its docs PR is the epic's closing bookend, and its merge closes the epic. Seed it at creation (title Retrospective: <epic-slug>), homed in the epic's home repo.
• Follow-on brainstorm — semi-optional (forward axis). Reviewing what shipped and brainstorming the follow-on epic(s) is a forward-looking concern that no longer defines the end of an epic. Seed it as a bookend only when a known enabling chain exists at creation ("we're building this specifically to unlock X/Y/Z"); otherwise accrue it as specific follow-on tasks during implementation, or skip it when there is nothing to chain. Its outcomes are recorded in the retrospective's §5.