246 lines
8.8 KiB
Markdown
246 lines
8.8 KiB
Markdown
---
|
|
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 and re-run the producer gate.
|
|
If [C]: stop. Verdict: **BLOCKED** — user wants to reconsider epic scope.
|
|
|
|
Do not write epic files until the producer gate resolves.
|
|
|
|
---
|
|
|
|
## 5. Write Epic Files
|
|
|
|
After approval, ask: "May I write the epic file to `production/epics/[epic-slug]/EPIC.md`?"
|
|
|
|
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 |
|
|
|-----|-----------------|-------------|
|
|
| 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
|
|
|
|
This epic is complete when:
|
|
- All stories are implemented, reviewed, and closed via `/story-done`
|
|
- All acceptance criteria from `design/gdd/[filename].md` are 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`
|
|
|
|
Create or update the master index:
|
|
|
|
```markdown
|
|
# Epics Index
|
|
|
|
Last Updated: [date]
|
|
Engine: [name + version]
|
|
|
|
| Epic | Layer | System | GDD | Stories | Status |
|
|
|------|-------|--------|-----|---------|--------|
|
|
| [name] | Foundation | [system] | [file] | Not yet created | Ready |
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Gate-Check Reminder
|
|
|
|
After writing all epics for the requested scope:
|
|
|
|
- **Foundation + Core complete**: These are required for the Pre-Production →
|
|
Production gate. Run `/gate-check production` to check readiness.
|
|
- **Reminder**: Epics define scope. Stories define implementation steps. 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, and architecture docs
|
|
5. **Never create stories** — this skill stops at the epic level
|
|
|
|
After all requested epics are 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.
|