/create-epics

name: create-epics
description: "Translate approved GDDs + architecture into epics — one epic per architectural module. Defines scope, governing ADRs, engine risk, and untraced requirements. Does NOT break into stories — run /create-stories [epic-slug] after each epic is created."
argument-hint: "[system-name | layer: foundation|core|feature|presentation | all] [--review full|lean|solo]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Write, Task, AskUserQuestion
model: sonnet
agent: technical-director

Create Epics

An epic is a named, bounded body of work that maps to one architectural module. It defines **what** needs to be built and **who owns it architecturally**. It does not prescribe implementation steps — that is the job of stories.

**Run this skill once per layer** as you approach that layer in development. Do not create Feature layer epics until Core is nearly complete — the design will have changed.

**Output:** `production/epics/[epic-slug]/EPIC.md` + `production/epics/index.md`

**Next step after each epic:** `/create-stories [epic-slug]`

**When to run:** After `/create-control-manifest` and `/architecture-review` pass.

---

1. Parse Arguments

Resolve the review mode (once, store for all gate spawns this run): 1. If `--review [full|lean|solo]` was passed → use that 2. Else read `production/review-mode.txt` → use that value 3. Else → default to `lean`

See `.claude/docs/director-gates.md` for the full check pattern.

**Modes:**

• `/create-epics all` — process all systems in layer order
• `/create-epics layer: foundation` — Foundation layer only
• `/create-epics layer: core` — Core layer only
• `/create-epics layer: feature` — Feature layer only
• `/create-epics layer: presentation` — Presentation layer only
• `/create-epics [system-name]` — one specific system
• No argument — ask: "Which layer or system would you like to create epics for?"

---

2. Load Inputs

Step 2a — Summary scan (fast)

Grep all GDDs for their `## Summary` sections before reading anything fully:

Grep pattern="## Summary" glob="design/gdd/*.md" output_mode="content" -A 5

For `layer:` or `[system-name]` modes: filter to only in-scope GDDs based on the Summary quick-reference. Skip full-reading anything out of scope.

Step 2b — Full document load (in-scope systems only)

Using the Step 2a grep results, identify which systems are in scope. Read full documents **only for in-scope systems** — do not read GDDs or ADRs for out-of-scope systems or layers.

Read for in-scope systems:

• `design/gdd/systems-index.md` — authoritative system list, layers, priority
• In-scope GDDs only (Approved or Designed status, filtered by Step 2a results)
• `docs/architecture/architecture.md` — module ownership and API boundaries
• Accepted ADRs **whose domains cover in-scope systems only** — read the "GDD Requirements Addressed", "Decision", and "Engine Compatibility" sections; skip ADRs for unrelated domains
• `docs/architecture/control-manifest.md` — manifest version date from header
• `docs/architecture/tr-registry.yaml` — for tracing requirements to ADR coverage
• `docs/engine-reference/[engine]/VERSION.md` — engine name, version, risk levels

Report: "Loaded [N] GDDs, [M] ADRs, engine: [name + version]."

---

3. Processing Order

Process in dependency-safe layer order: 1. **Foundation** (no dependencies) 2. **Core** (depends on Foundation) 3. **Feature** (depends on Core) 4. **Presentation** (depends on Feature + Core)

Within each layer, use the order from `systems-index.md`.

---

4. Define Each Epic

For each system, map it to an architectural module from `architecture.md`.

Check ADR coverage against the TR registry:

• **Traced requirements**: TR-IDs that have an Accepted ADR covering them
• **Untraced requirements**: TR-IDs with no ADR — warn before proceeding

Present to user before writing anything:

## Epic: [System Name]

**Layer**: [Foundation / Core / Feature / Presentation]
**GDD**: design/gdd/[filename].md
**Architecture Module**: [module name from architecture.md]
**Governing ADRs**: [ADR-NNNN, ADR-MMMM]
**Engine Risk**: [LOW / MEDIUM / HIGH — highest risk among governing ADRs]
**GDD Requirements Covered by ADRs**: [N / total]
**Untraced Requirements**: [list TR-IDs with no ADR, or "None"]

If there are untraced requirements: > "⚠️ [N] requirements in [system] have no ADR. The epic can be created, but > stories for these requirements will be marked Blocked until ADRs exist. > Run `/architecture-decision` first, or proceed with placeholders."

Use `AskUserQuestion`:

• Prompt: "Shall I create Epic: [name]?"
• Options:
• `[A] Yes, create it`
• `[B] Skip this epic`
• `[C] Pause — I need to write ADRs first`

---

4b. Producer Epic Structure Gate

**Review mode check** — apply before spawning PR-EPIC:

• `solo` → skip. Note: "PR-EPIC skipped — Solo mode." Proceed to Step 5 (write epic files).
• `lean` → skip (not a PHASE-GATE). Note: "PR-EPIC skipped — Lean mode." Proceed to Step 5 (write epic files).
• `full` → spawn as normal.

After all epics for the current layer are defined (Step 4 completed for all in-scope systems), and before writing any files, spawn `producer` via Task using gate **PR-EPIC** (`.claude/docs/director-gates.md`).

Pass: the full epic structure summary (all epics, their scope summaries, governing ADR counts), the layer being processed, milestone timeline and team capacity.

Present the producer's assessment.

If UNREALISTIC: offer to revise epic boundaries (split overscoped or merge underscoped epics). Revise and re-run the gate before writing.

If CONCERNS, use `AskUserQuestion`:

• Prompt: "Producer raised concerns about the epic structure. How do you want to proceed?"
• Options:
• `[A] Proceed as planned — I accept the producer's concerns`
• `[B] Revise epic boundaries — split or merge as recommended`
• `[C] Stop — I want to reconsider the scope`

If [A]: proceed to Step 5. If [B]: revise epic definitions from Step 4 an