pixelheros/CCGS Skill Testing Framework/skills/pipeline/create-epics.md

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.