# Skill Test Spec: /create-epics

## Skill Summary

`/create-epics` reads all approved GDDs and translates them into EPIC.md files,
one per system. Epics are organized by layer (Foundation → Core → Feature →
Presentation) and processed in priority order within each layer. Each EPIC.md
includes scope, governing ADRs, GDD requirements, engine risk level, and a
Definition of Done. The skill asks "May I write" before creating each EPIC file.

In `full` review mode, a PR-EPIC gate (producer) runs after drafting epics and
before writing any files. In `lean` or `solo` mode, PR-EPIC is skipped and noted.
Epics are written to `production/epics/[layer]/EPIC-[name].md`.

---

## Static Assertions (Structural)

Verified automatically by `/skill-test static` — no fixture needed.

- [ ] Has required frontmatter fields: `name`, `description`, `argument-hint`, `user-invocable`, `allowed-tools`
- [ ] Has ≥2 phase headings
- [ ] Contains verdict keywords: CREATED, BLOCKED
- [ ] Contains "May I write" collaborative protocol language (per-epic approval)
- [ ] Has a next-step handoff at the end (`/create-stories`)
- [ ] Documents PR-EPIC gate behavior: runs in full mode; skipped in lean/solo

---

## Director Gate Checks

In `full` mode: PR-EPIC (producer) gate runs after epics are drafted and before
any epic file is written. If PR-EPIC returns CONCERNS, epics are revised before
the "May I write" ask.

In `lean` mode: PR-EPIC is skipped. Output notes: "PR-EPIC skipped — lean mode".

In `solo` mode: PR-EPIC is skipped. Output notes: "PR-EPIC skipped — solo mode".

---

## Test Cases

### Case 1: Happy Path — Two approved GDDs create two EPIC files

**Fixture:**
- `design/gdd/systems-index.md` exists with 2 systems listed
- Both systems have approved GDDs in `design/gdd/`
- `docs/architecture/architecture.md` exists with matching modules
- At least one Accepted ADR exists for each system
- `production/session-state/review-mode.txt` contains `lean`

**Input:** `/create-epics`

**Expected behavior:**
1. Skill reads systems index and both GDDs
2. Drafts 2 EPIC definitions (layer, GDD path, ADRs, requirements, engine risk)
3. PR-EPIC gate is skipped (lean mode) — noted in output
4. For each epic: asks "May I write `production/epics/[layer]/EPIC-[name].md`?"
5. After approval: writes both EPIC files
6. Creates or updates `production/epics/index.md`

**Assertions:**
- [ ] Epic summary is shown before any write ask
- [ ] "May I write" is asked per-epic (not once for all epics together)
- [ ] Each EPIC.md contains: layer, GDD path, governing ADRs, requirements table, Definition of Done
- [ ] PR-EPIC skip is noted in output
- [ ] `production/epics/index.md` is updated after writing
- [ ] Skill does NOT write EPIC files without per-epic approval

---

### Case 2: Failure Path — No approved GDDs found

**Fixture:**
- `design/gdd/systems-index.md` exists
- No GDDs in `design/gdd/` have approved status (all are Draft or In Progress)

**Input:** `/create-epics`

**Expected behavior:**
1. Skill reads systems index and attempts to find approved GDDs
2. No approved GDDs found
3. Skill outputs: "No approved GDDs to convert. GDDs must be Approved before creating epics."
4. Skill suggests running `/design-system` and completing GDD approval first
5. Skill exits without creating any EPIC files

**Assertions:**
- [ ] Skill stops cleanly with a clear message when no approved GDDs exist
- [ ] No EPIC files are written
- [ ] Skill recommends the correct next action
- [ ] Verdict is BLOCKED

---

### Case 3: Director Gate — Full mode spawns PR-EPIC before writing

**Fixture:**
- 2 approved GDDs exist
- `production/session-state/review-mode.txt` contains `full`

**Full mode expected behavior:**
1. Skill drafts both epics
2. PR-EPIC gate spawns and reviews the epic drafts
3. If PR-EPIC returns APPROVED: "May I write" ask proceeds normally
4. Epic files are written after approval

**Assertions (full mode):**
- [ ] PR-EPIC gate appears in output as an active gate
- [ ] PR-EPIC runs before any "May I write" ask
- [ ] Epic files are NOT written before PR-EPIC completes

**Fixture (lean mode):**
- Same GDDs
- `production/session-state/review-mode.txt` contains `lean`

**Lean mode expected behavior:**
1. Epics are drafted
2. PR-EPIC is skipped — noted in output
3. "May I write" ask proceeds directly

**Assertions (lean mode):**
- [ ] "PR-EPIC skipped — lean mode" appears in output
- [ ] Skill proceeds to "May I write" without waiting for PR-EPIC

---

### Case 4: Edge Case — Epic already exists for a GDD

**Fixture:**
- `production/epics/[layer]/EPIC-[name].md` already exists for one of the approved GDDs
- The other GDD has no existing EPIC file

**Input:** `/create-epics`

**Expected behavior:**
1. Skill detects the existing EPIC file for the first system
2. Skill offers to update rather than overwrite: "EPIC-[name].md already exists. Update it, or skip?"
3. For the second system (no existing file): proceeds normally with "May I write"

**Assertions:**
- [ ] Skill detects existing EPIC files before writing
- [ ] User is offered "update" or "skip" options — not auto-overwritten
- [ ] The new system's EPIC is created normally without conflict

---

### Case 5: Director Gate — PR-EPIC returns CONCERNS

**Fixture:**
- 2 approved GDDs exist
- `production/session-state/review-mode.txt` contains `full`
- PR-EPIC gate returns CONCERNS (e.g., scope of one epic is too large)

**Input:** `/create-epics`

**Expected behavior:**
1. PR-EPIC gate spawns and returns CONCERNS with specific feedback
2. Skill surfaces the concerns to the user before any write ask
3. User is given options: revise epics, accept concerns and proceed, or stop
4. If user revises: updated epic drafts are shown before the "May I write" ask
5. Skill does NOT write epics while CONCERNS are unaddressed

**Assertions:**
- [ ] CONCERNS from PR-EPIC are shown to the user before writing
- [ ] Skill does NOT auto-write epics when CONCERNS are returned
- [ ] User is given a clear choice to revise, proceed, or stop
- [ ] Revised epic drafts are re-shown after revision before final approval

---

## Protocol Compliance

- [ ] Epic drafts shown to user before any "May I write" ask
- [ ] "May I write" asked per-epic, not once for the entire batch
- [ ] PR-EPIC gate (if active) runs before write asks — not after
- [ ] Skipped gates noted by name and mode in output
- [ ] EPIC.md content sourced only from GDDs, ADRs, and architecture docs — nothing invented
- [ ] Ends with next-step handoff: `/create-stories [epic-slug]` per created epic

---

## Coverage Notes

- Processing of Core, Feature, and Presentation layers follows the same per-epic
  pattern as Foundation — layer-specific ordering is not independently tested.
- Engine risk level assignment (LOW/MEDIUM/HIGH) from governing ADRs is
  validated implicitly via Case 1's fixture structure.
- The `layer: [name]` and `[system-name]` argument modes follow the same approval
  pattern as the default (all systems) mode.
