Create Epics

🌱 ShiningPlague-adopted. Originally Donchitos; battle-tested on a shipped Godot project. Upstream procedure preserved + project path corrections.

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. Don't 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.

If an artifact named here is absent: say so plainly in one line, skip that step, and continue. Never invent the file to satisfy a checklist, and never fail a close because an optional artifact was never created.

Project Paths

Notes:

• If no production/epics/ directory exists yet, this run creates it.
• If per-system GDDs don't exist yet, epics derive from master GDD sections + ADRs.
• Small path (spec → ADR → plan → execute) covers 1-2 week work; the large path (with epics) activates when scope exceeds that.

1. Parse Arguments

Resolve the review mode:

1. If --review [full|lean|solo] was passed → use that
2. Else read production/review-mode.txt
3. Else → default to lean

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 ## Summary:

Grep pattern="## Summary" glob="docs/gdd/*.md" output_mode="content" -A 5
Grep pattern="^## [0-9]" path="{{GDD_PATH}}" output_mode="content" -A 2

For layer: or [system-name] modes: filter to in-scope GDDs.

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

For in-scope systems, read:

• docs/gdd/systems-index.md — authoritative system list, layers, priority
• In-scope GDDs only (Approved or Designed status)
• docs/architecture/architecture.md — module ownership and API boundaries
• Accepted ADRs covering in-scope systems — read "GDD Requirements Addressed", "Decision", "Engine Compatibility"
• docs/architecture/control-manifest.md — manifest version date from header
• docs/architecture/tr-registry.yaml — for tracing requirements to ADR coverage
• docs/engine-reference/godot/VERSION.md — engine name, version, risk levels

Report: "Loaded [N] GDDs, [M] ADRs, engine: Godot 4.6.1."

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 with Accepted ADR coverage
• 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**: docs/gdd/[filename].md (or {{GDD_PATH}} §[section])
**Architecture Module**: [module name from architecture.md]
**Governing ADRs**: [ADR-NNNN, ADR-MMMM]
**Engine Risk**: [LOW / MEDIUM / HIGH]
**GDD Requirements Covered by ADRs**: [N / total]
**Untraced Requirements**: [list TR-IDs with no ADR, or "None"]

If untraced:

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

Ask: "Shall I create Epic: [name]?" Options: "Yes, create it", "Skip", "Pause — I need to write ADRs first"

4b. Producer Epic Structure Gate

Review mode check before PR-EPIC:

• solo → skip. "PR-EPIC skipped — Solo mode." Proceed to Step 5.
• lean → skip. "PR-EPIC skipped — Lean mode." Proceed to Step 5.
• full → spawn as normal.

After all epics for current layer are defined and before writing any files, spawn producer via Task using gate PR-EPIC.

Pass: full epic structure summary, layer being processed, milestone timeline, team capacity.

Present producer's assessment. If UNREALISTIC, offer to revise epic boundaries. If CONCERNS, surface them.

5. Write Epic Files

After approval: "May I write the epic file to production/epics/[epic-slug]/EPIC.md?"

production/epics/[epic-slug]/EPIC.md

# Epic: [System Name]

> **Layer**: [Foundation / Core / Feature / Presentation]
> **GDD**: docs/gdd/[filename].md (or {{GDD_PATH}} §[section])
> **Architecture Module**: [module name]
> **Status**: Ready
> **Stories**: Not yet created — run `/create-stories [epic-slug]`

## Overview

[1 paragraph from GDD Overview and architecture module]

## Governing ADRs

| ADR | Decision Summary | Engine Risk |
|-----|-----------------|-------------|
| ADR-NNNN: [title] | [1-line summary] | LOW/MEDIUM/HIGH |

## GDD Requirements

| TR-ID | Requirement | ADR Coverage |
|-------|-------------|--------------|
| TR-[system]-001 | [requirement text from registry] | ADR-NNNN ✅ |
| TR-[system]-002 | [requirement text] | ❌ No ADR |

## Definition of Done

- All stories implemented, reviewed, closed via `/story-done`
- All acceptance criteria from GDD verified
- All Logic and Integration stories have passing test files in `tests/`
- All Visual/Feel and UI stories have evidence docs with sign-off in `production/qa/evidence/`

## Next Step

Run `/create-stories [epic-slug]` to break this epic into implementable stories.

Update production/epics/index.md

# Epics Index

Last Updated: [date]
Engine: Godot 4.6.1

| Epic | Layer | System | GDD | Stories | Status |
|------|-------|--------|-----|---------|--------|
| [name] | Foundation | [system] | [file] | Not yet created | Ready |

6. Gate-Check Reminder

• Foundation + Core complete: required for Pre-Production → Production gate. Run /gate-check production.
• Reminder: Epics define scope. Stories define implementation. Run /create-stories [epic-slug] for each epic before developers can pick up work.

Collaborative Protocol

1. One epic at a time — present each epic definition before asking to create it
2. Warn on gaps — flag untraced requirements before proceeding
3. Ask before writing — per-epic approval before writing any file
4. No invention — all content comes from GDDs, ADRs, architecture docs
5. Never create stories — this skill stops at the epic level

After all epics processed:

• Verdict: COMPLETE — [N] epic(s) written. Run /create-stories [epic-slug] per epic.
• Verdict: BLOCKED — user declined all epics, or no eligible systems found.