create-epics

!`bash "${CLAUDE_SKILL_DIR}/../../hooks/yaml-helper.sh" resolve_config --keys review_mode,automation,workflow,docs.density,story_granularity,system_overrides` Resolved above — use as-is; `--review` overrides `review_mode`. No block → defaults in `.claude/docs/config-resolution.md`. # 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 (at `full`). At `standard`, critical ADRs suffice, and a control manifest is read if present. At `minimal`, this skill is **optional and not part of the path** — `/create-stories` synthesizes the epic from `design/game-brief.md` itself (Option A). If run anyway, it decomposes directly from the brief with no GDD/ADR/manifest prerequisite. > **At `minimal`, this skill is optional — `/create-stories` synthesizes the epic** > (Option A). At that tier `/create-stories` reads `design/game-brief.md` > directly, writes a lightweight implicit `production/epics/<slug>/EPIC.md`, and > generates stories from the MVP list — so the path is `/brainstorm` → > `/create-stories` → `/dev-story`, with no separate `/create-epics` or > `/sprint-plan` step. **At `standard`/`full` an epic IS required**: > `/create-stories` reads `production/epics/[slug]/EPIC.md`, and skipping this > skill there leaves `/dev-story` with no story to implement — a dead end, not a > shortcut. --- ## 1. Parse Arguments See `.claude/docs/director-gates.md` for the full check pattern. Individual gate definitions live in `.claude/docs/director-gates/[gate-id].md` — the spawned agent reads its own gate file; do not read it in the parent session. Every `AskUserQuestion` call follows `.claude/docs/automation-modes.md` (collaborative asks always · guided major-only · autonomous logs and proceeds; `automation_always_ask` categories always prompt). **`workflow`** (per `.claude/docs/workflow-modes.md`): create-epics runs project-wide: it uses the project-level tier for its prerequisite expectations and consults `workflow_overrides.system_overrides.<system>` per-system when reading each in-scope GDD. See "Workflow tier adjustment" in Step 2. **`story_granularity`** — it sizes the epic's story breakdown: expect **3–5** child stories per epic at `coarse` (the default, via `rigor: minimal`), **5–10** at `balanced` (`rigor: standard`), **10–20** at `fine`. **`docs.density`** — it controls the *depth* of each epic's written scope and rationale, not the story count (that is `story_granularity`). `modes.rigor` sets it alongside `workflow`; set `docs.density` explicitly to vary epic prose alone: `terse` (the default, via `rigor: minimal`) = scope as bullets, one-line rationale; `balanced` = a scope paragraph with light rationale (`rigor: standard`); `thorough` = full scope prose with governing-ADR rationale and risk discussion. The EPIC.md tables (GDD requirements, governing ADRs) are structural and stay whole at every density. **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, fail-open) **At `minimal`, skip Steps 2a and 2b** — that tier decomposes from `design/game-brief.md` and has no GDDs by design (see the tier note below). Read the brief instead; if it is missing, report "No `design/game-brief.md` — run `/start` or `/brainstorm` first" and stop. **At `standard` and `full`, establish the denominator first.** Glob `design/gdd/*.md`, excluding the non-system docs — `game-concept.md`, `systems-index.md`, `game-pillars.md`, `gameplay-tags.md`, `entity-registry.md`, `fixture-swap-ledger.md`, any `gdd-cross-review-*.md`, `sound-bible.md` — the set `gdd-structure-check.sh` skips (the sound bible belongs in `design/audio/`; it is listed for projects that still keep it at the earlier location). Call the count **N**. If N is 0, there are no system GDDs — report "No system GDDs found in `design/gdd/` — run `/design-system` first" and stop. Scan for Summary sections: ``` Grep pattern="^## Summary" glob="design/gdd/*.md" output_mode="content" -A 5 ``` Interpret the **M** matches against N. These are three different outcomes, and a zero-match scan is **never** the same as "nothing in scope": | Result | Meaning | Action | |---|---|---| | **M = N** | Every GDD has a Summary. | For `layer:`/`[system-name]` modes, use the Summary Quick-reference (Layer/Priority) to pick the in-scope set; skip full-reading the rest. | | **0 < M < N** | Partial adoption — older GDDs predate `## Summary`. | Scope the M by their Summaries; determine the scope of the **N − M** unmatched from `systems-index.md` (layer/priority) and full-read those. | | **0 matches, N > 0** | Expected for GDDs authored before `/design-system` emitted `## Summary`. | Determine scope for **all N** from `systems-index.md` and full-read the in-scope set. This is the pre-optimization behaviour — correct, only more expensive. Note once: "No `## Summary` sections found across [N] GDDs — scoping from `systems-index.md` instead of Summary." | **Never treat an absent `## Summary` as an absent system.** The scan narrows the *read* set when it succeeds; it never shrinks the *in-scope* set. In `all` mode every system is in scope regardless of Summary, so the scan is a convenience only — never a filter. ### 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** — skip ADRs for unrelated domains entirely. For each in-scope ADR, load only the "GDD Requirements Addressed", "Decision", and "Engine Compatibility" sections — never an unbounded full read: ``` Grep pattern="^## (GDD Requirements Addressed|Decision|Engine Compatibility)" path="docs/architecture/[adr-file].md" output_mode="content" -n ``` then `Read(offset, limit)` bounded to each match through the next `## ` heading (or to end of file for the last match). This matters most on a large ADR. - `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]." > **Workflow tier adjustment** (resolved in Step 1; per-system via > `system_overrides`). The inputs above are the `full` baseline: > - **`full`** — every in-scope GDD must be Approved with all 8 sections; TR > registry + control manifest are required inputs; untraced requirements > (Step 4) are flagged before proceeding. > - **`standard`** — GDDs need the 5 required sections (+ conditional Formulas) > approved; only **critical (Foundation-layer) ADRs** are expected; the control > manifest is read if present, not required. A system pinned higher via > `system_overrides` must still meet its higher bar. > - **`minimal`** — decompose against `design/game-brief.md` + > acceptance criteria. Do not require GDDs, ADRs, the TR registry, or the > manifest; skip the untraced-requirement gate. If run, the epic is still > produced — but note `/create-stories` also synthesizes one from the brief when > this skill is skipped (the default `minimal` path). --- ## 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`. > **At `minimal` there is no `systems-index.md`** — `/map-systems` is not required > at that tier, so nothing has produced one. Derive the layer split and ordering > from `design/game-brief.md` instead: its **Build order** field names what must > exist first. Do not stop, and do not send the user to `/map-systems` to satisfy > an ordering hint — the tier deliberately skips it. --- ## 4. Define Each Epic For each system, map it to an architectural module from `architecture.md`. Check ADR coverage against the TR registry **per the resolved tier** (Step 1): - **`full`** — trace every TR-ID; warn on each untraced requirement (below). - **`standard`** — only **critical (Foundation-layer) ADRs** are expected; trace those. Treat untraced non-critical requirements as informational (list them, do not block or emit the untraced-requirements warning). - **`minimal`** — skip this check entirely (no TR registry / ADR expected). - **Traced requirements**: TR-IDs that have an Accepted ADR covering them - **Untraced requirements**: TR-IDs with no ADR — warn before proceeding (full only) 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 > `/create-stories` will write their stories with no governing ADR (`ADR: N/A`) > and `Status: Ready` — nothing downstream blocks them, so they would be > implemented without architectural guidance. Run `/architecture-decision` first > if they need a decision, or proceed and accept the gap." 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 `Agent` using gate **PR-EPIC** (`.claude/docs/director-gates/pr-epic.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, present the revised epics again, 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, present the revised epics to the user again, then re-run the producer gate. If [C]: stop. Verdict: **BLOCKED** — user wants to reconsider epic scope. If NOT ASSESSED [missing input] — e.g. no milestone timeline or team capacity — it is not a REALISTIC (`.claude/docs/director-gates.md`): name what was missing, then supply it and re-run the gate, or, if the user chooses to go on without it, proceed to Step 5 and state `PR-EPIC: NOT ASSESSED — [input]` in the output and the final Verdict line. Do not write epic files until the producer gate resolves. --- ## 5. Write Epic Files **If `production/epics/[epic-slug]/EPIC.md` already exists, never overwrite it.** Ask instead: "An EPIC.md already exists for [name]. Update it in place, or skip it?" — `[A] Update in place — keep its Stories table, and update its index.md row` / `[B] Skip this epic`. An update rewrites only what this skill owns — the header fields other than `Stories`, `## Overview`, `## Governing ADRs`, `## GDD Requirements` and `## Definition of Done` — and leaves the `**Stories**` header line and any `## Stories` table exactly as they are: `/create-stories` wrote them, and resetting them to "Not yet created" orphans every story already in the directory. For a new epic, after approval, ask: "May I write `production/epics/[epic-slug]/EPIC.md` and add its row to `production/epics/index.md` (creating it if absent)?" After user confirms, write: ### `production/epics/[epic-slug]/EPIC.md` ```markdown # Epic: [System Name] > **Layer**: [Foundation / Core / Feature / Presentation] > **GDD**: design/gdd/[filename].md > **Architecture Module**: [module name] > **Status**: Ready > **Stories**: Not yet created — run `/create-stories [epic-slug]` ## Overview [1 paragraph describing what this epic implements, derived from the GDD Overview and the architecture module's stated responsibilities] ## Governing ADRs | ADR | Decision Summary | Engine Risk | |-----|-----------------|-------------|