7.4 KiB
Skill Test Spec: /create-stories
Skill Summary
/create-stories breaks a single epic into developer-ready story files. It reads
the EPIC.md, the corresponding GDD, governing ADRs, the control manifest, and the
TR registry. Each story gets structured frontmatter including: Title, Epic, Layer,
Priority, Status, TR-ID, ADR references, Acceptance Criteria, and Definition of
Done. Stories are classified by type (Logic / Integration / Visual/Feel / UI /
Config/Data) which determines the required test evidence path.
In full review mode, a QL-STORY-READY check runs per story after creation. In
lean or solo mode, QL-STORY-READY is skipped. The skill asks "May I write"
before writing each story file. Stories are written to
production/epics/[layer]/story-[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: COMPLETE, BLOCKED, NEEDS WORK
- Contains "May I write" collaborative protocol language (per-story approval)
- Has a next-step handoff at the end (
/story-readiness,/dev-story) - Documents story Status: Blocked when governing ADR is Proposed
- Documents QL-STORY-READY gate: active in full mode, skipped in lean/solo
Director Gate Checks
In full mode: QL-STORY-READY check runs per story after creation. Stories that
fail the check are noted as NEEDS WORK before the "May I write" ask.
In lean mode: QL-STORY-READY is skipped. Output notes:
"QL-STORY-READY skipped — lean mode" per story.
In solo mode: QL-STORY-READY is skipped with equivalent notes.
Test Cases
Case 1: Happy Path — Epic with 3 stories, all ADRs Accepted
Fixture:
production/epics/[layer]/EPIC-[name].mdexists with 3 GDD requirements- Corresponding GDD exists with matching acceptance criteria
- All governing ADRs have
Status: Accepted docs/architecture/control-manifest.mdexistsdocs/architecture/tr-registry.yamlhas TR-IDs for all 3 requirementsproduction/session-state/review-mode.txtcontainslean
Input: /create-stories [epic-name]
Expected behavior:
- Skill reads EPIC.md, GDD, governing ADRs, control manifest, and TR registry
- Classifies each requirement into a story type (Logic / Integration / Visual/Feel / UI / Config/Data)
- Drafts 3 story files with correct frontmatter schema
- QL-STORY-READY is skipped (lean mode) — noted in output
- Asks "May I write" before writing each story file
- Writes all 3 story files after approval
Assertions:
- Each story's frontmatter contains: Title, Epic, Layer, Priority, Status, TR-ID, ADR reference, Acceptance Criteria, DoD
- Story types are correctly classified (at least one Logic type in fixture)
- "May I write" is asked per story (not once for the entire batch)
- QL-STORY-READY skip is noted in output
- All 3 story files are written with correct naming:
story-[name].md - Skill does NOT start implementation
Case 2: Failure Path — No epic file found
Fixture:
- The epic path provided does not exist in
production/epics/
Input: /create-stories nonexistent-epic
Expected behavior:
- Skill attempts to read the EPIC.md file
- File not found
- Skill outputs a clear error with the path it searched
- Skill suggests checking
production/epics/or running/create-epicsfirst - No story files are created
Assertions:
- Skill outputs a clear error naming the missing file path
- No story files are written
- Skill recommends the correct next action (
/create-epics) - Skill does NOT create stories without a valid EPIC.md
Case 3: Blocked Story — ADR is Proposed
Fixture:
- EPIC.md exists with 2 requirements
- Requirement 1 is covered by an Accepted ADR
- Requirement 2 is covered by an ADR with
Status: Proposed
Input: /create-stories [epic-name]
Expected behavior:
- Skill reads the ADR for Requirement 2 and finds Status: Proposed
- Story for Requirement 2 is drafted with
Status: Blocked - Blocking note references the specific ADR: "BLOCKED: ADR-NNN is Proposed"
- Story for Requirement 1 is drafted normally with
Status: Ready - Both stories are shown in the draft — user asked "May I write" for both
Assertions:
- Story 2 has
Status: Blockedin its frontmatter - Blocking note names the specific ADR number and recommends
/architecture-decision - Story 1 has
Status: Ready— blocked status does not affect non-blocked stories - Blocked status is shown in the draft preview before writing
- Both story files are written (blocked stories are still written — just flagged)
Case 4: Edge Case — No argument provided
Fixture:
production/epics/directory exists with ≥2 epic subdirectories
Input: /create-stories (no argument)
Expected behavior:
- Skill detects no argument is provided
- Outputs a usage error: "No epic specified. Usage: /create-stories [epic-name]"
- Skill lists available epics from
production/epics/ - No story files are created
Assertions:
- Skill outputs a usage error when no argument is given
- Skill lists available epics to help the user choose
- No story files are written
- Skill does NOT silently pick an epic without user input
Case 5: Director Gate — Full mode runs QL-STORY-READY; stories failing noted as NEEDS WORK
Fixture:
- EPIC.md exists with 2 requirements
- Both governing ADRs are Accepted
production/session-state/review-mode.txtcontainsfull- QL-STORY-READY check finds one story has ambiguous acceptance criteria
Input: /create-stories [epic-name]
Expected behavior:
- Both stories are drafted
- QL-STORY-READY check runs for each story
- Story 1 passes QL-STORY-READY
- Story 2 fails QL-STORY-READY — noted as NEEDS WORK with specific feedback
- Both stories are shown to user with pass/fail status before "May I write"
- User can proceed (story written as-is with NEEDS WORK note) or revise first
Assertions:
- QL-STORY-READY results appear per story in the output
- Story 2 is flagged as NEEDS WORK with the specific failing criteria
- Story 1 shows as passing QL-STORY-READY
- User is given the choice to proceed or revise before writing
- Skill does NOT auto-block writing of stories that fail QL-STORY-READY without user input
Protocol Compliance
- All context (EPIC, GDD, ADRs, manifest, TR registry) loaded before drafting stories
- Story drafts shown in full before any "May I write" ask
- "May I write" asked per story (not once for the entire batch)
- Blocked stories flagged before write approval — not discovered after writing
- TR-IDs reference the registry — requirement text is not embedded inline in story files
- Control manifest rules quoted per-story from the manifest, not invented
- Ends with next-step handoff:
/story-readiness→/dev-story
Coverage Notes
- Integration story test evidence (playtest doc alternative) follows the same approval pattern as Logic stories — not independently fixture-tested.
- Story ordering (foundational first, UI last) is validated implicitly via Case 1's multi-story fixture.
- The story sizing rule (splitting large requirement groups) is not tested here
— it is addressed in the
/create-storiesskill's internal logic.