192 lines
7.4 KiB
Markdown
192 lines
7.4 KiB
Markdown
# 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].md` exists with 3 GDD requirements
|
|
- Corresponding GDD exists with matching acceptance criteria
|
|
- All governing ADRs have `Status: Accepted`
|
|
- `docs/architecture/control-manifest.md` exists
|
|
- `docs/architecture/tr-registry.yaml` has TR-IDs for all 3 requirements
|
|
- `production/session-state/review-mode.txt` contains `lean`
|
|
|
|
**Input:** `/create-stories [epic-name]`
|
|
|
|
**Expected behavior:**
|
|
1. Skill reads EPIC.md, GDD, governing ADRs, control manifest, and TR registry
|
|
2. Classifies each requirement into a story type (Logic / Integration / Visual/Feel / UI / Config/Data)
|
|
3. Drafts 3 story files with correct frontmatter schema
|
|
4. QL-STORY-READY is skipped (lean mode) — noted in output
|
|
5. Asks "May I write" before writing each story file
|
|
6. 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:**
|
|
1. Skill attempts to read the EPIC.md file
|
|
2. File not found
|
|
3. Skill outputs a clear error with the path it searched
|
|
4. Skill suggests checking `production/epics/` or running `/create-epics` first
|
|
5. 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:**
|
|
1. Skill reads the ADR for Requirement 2 and finds Status: Proposed
|
|
2. Story for Requirement 2 is drafted with `Status: Blocked`
|
|
3. Blocking note references the specific ADR: "BLOCKED: ADR-NNN is Proposed"
|
|
4. Story for Requirement 1 is drafted normally with `Status: Ready`
|
|
5. Both stories are shown in the draft — user asked "May I write" for both
|
|
|
|
**Assertions:**
|
|
- [ ] Story 2 has `Status: Blocked` in 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:**
|
|
1. Skill detects no argument is provided
|
|
2. Outputs a usage error: "No epic specified. Usage: /create-stories [epic-name]"
|
|
3. Skill lists available epics from `production/epics/`
|
|
4. 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.txt` contains `full`
|
|
- QL-STORY-READY check finds one story has ambiguous acceptance criteria
|
|
|
|
**Input:** `/create-stories [epic-name]`
|
|
|
|
**Expected behavior:**
|
|
1. Both stories are drafted
|
|
2. QL-STORY-READY check runs for each story
|
|
3. Story 1 passes QL-STORY-READY
|
|
4. Story 2 fails QL-STORY-READY — noted as NEEDS WORK with specific feedback
|
|
5. Both stories are shown to user with pass/fail status before "May I write"
|
|
6. 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-stories` skill's internal logic.
|