| name | generate-user-stories |
| description | Decomposes features into story concepts using the WAHZURT framework, then creates detailed INVEST-compliant user stories one-at-a-time with quality gates. Supports 4 modes: create (standard), create (quick/draft), modify existing stories, or decompose-only. Use when asked to: create user stories, write stories, generate stories, decompose an epic, break down a feature, plan stories, write acceptance criteria, modify a story, improve a story, enhance a story, or update a story. |
Generate User Stories — Entry Orchestrator
⚠️ Execution Discipline
You are now operating under this skill's instructions exclusively.
BEFORE generating ANY output, verify:
- Have I read the workflow file for this step?
- Have I completed ALL prior stages per the state file?
- Has the user explicitly approved the last checkpoint?
If ANY answer is NO → stop. Read the correct workflow file.
NEVER generate stories without following the workflow files.
🎯 Purpose
Decompose features into story concepts, then create detailed user stories one-at-a-time with inline quality gates.
Each story is saved as an individual file. A story registry tracks cross-story coherence.
What you'll get:
[output-folder]/[platform]-story-[N]-[name].md — individual story files (root folder, clean)[output-folder]/.meta/ — intermediate artifacts:
Decomposition-[Feature].md — story concept list with coverage mapstory-registry.md — cumulative cross-story trackerStory-Prepare-[Feature].md — extracted context from inputs.pipeline-state.json — stage tracking
Core principle: A user story is a communication tool first. Its purpose is to transfer enough understanding to the people who build and test it — clearly enough that they don't need to stop and ask. If it fails that, it fails its job.
The real test — two cold reads, both must pass:
- Developer: Can someone pick this up cold, read it once, and know what to build?
- QA: Can someone pick this up cold, read it once, and know how to verify it's done?
🔗 When Called from /story-pipeline
When invoked from story-pipeline, skip Steps 1-3 (scoping gate, project context, intake). The pipeline provides feature name, inputs, output folder, and project context.
Go directly to Step 4 with all values pre-loaded, then read the appropriate workflow file.
🔄 Workflow Chain
[You are here]
SKILL.md (Intake + Mode Detection)
↓ reads (based on mode)
workflows/01-prepare.md → validates inputs, determines starting point
↓ reads
workflows/02-decompose.md → WAHZURT analysis → story concepts + coverage map
↓ reads
workflows/03-create-story.md → creates stories via sub-agents, registry, grouped approval
↓ reads
workflows/04-set-review.md → cross-story coherence check
↓ (MODIFY mode only)
workflows/05-modify-story.md → targeted edits to existing stories
📥 Step 1: Three-Tier Scoping Gate
Never scan the full workspace by default. Progressive, user-confirmed scoping.
Tier 1: User-Provided Files (always included)
Files/folders referenced, URLs pasted, verbal descriptions. No confirmation needed.
Tier 2: Same-Folder Scan (user selects)
Glob parent folder(s) of provided files. Present grouped by type (requirements, epics, existing stories). User selects. Unselected never read.
Tier 3: Workspace-Wide Search (opt-in only)
After Tier 2, offer broader search. If accepted: keyword search from Tier 1+2 content. If declined: proceed with Tier 1+2 only.
Final Input Set
Lock inputs after scoping. No additional files read unless user provides later.
📂 Step 1.5: Load Project Context
Check for project-context.md in the workspace root.
IF found: Read and extract: personas, stack, integrations, constraints, glossary.
IF not found: Proceed without it. Offer /project-context after completion.
📋 Step 2: Gather Required Context
For this story set, I need:
1. Feature name
2. Input source — which do you have?
- [ ] Decomposition file (from prior run)
- [ ] Epic document
- [ ] Feature Requirements document
- [ ] Just your description (Quick/Draft mode)
3. Output folder — where should stories be saved?
🔀 Step 3: Mode Detection
| Mode | Signal | Route |
|---|
| CREATE (Standard) | "create", "write", "generate" + structured input (requirements doc, epic, decomposition) | All stages: 01-prepare → 02-decompose → 03-create → 04-set-review |
| CREATE (Quick) | "create", "write" + only verbal input, no structured doc | 01-prepare → 02-decompose (lighter) → 03-create (stories marked [DRAFT]) |
| MODIFY | "modify", "improve", "enhance", "update", "change" + existing story referenced | Direct to 05-modify-story |
| DECOMPOSE only | "decompose", "break down", "plan stories" | 01-prepare → 02-decompose only |
Quick mode warning:
No requirements doc found. I can create draft stories from your description,
but they'll be marked [DRAFT — requires requirements doc for production quality].
For production stories, run /generate-requirements first.
⚡ Step 3.5: Pre-Flight Checks
| Check | Source | Action if missing |
|---|
| Feature name captured | User input | Required — ask |
| At least 1 input source | User input or scan | Required — verbal qualifies |
| Mode determined | Keywords + input type | Required — infer or ask |
| Output folder confirmed | User input | Required — ask |
| Project context loaded? | project-context.md | Optional — proceed without |
| Design files provided? | Workspace or user | If Figma URL: verify processed through design-to-context. Unprocessed URL cannot be cited. |
Processing Verification Gate (if design files provided)
Every design URL routed to design-to-context MUST have saved output before proceeding.
URL alone is NOT a processed output. ❌ = run the skill immediately.
🚀 Step 4: Route to Workflow
Determine starting point based on available inputs:
| Input Available | Start From |
|---|
| Decomposition file from prior run | workflows/03-create-story.md (skip decompose) |
| Epic or requirements doc | workflows/01-prepare.md → 02-decompose.md |
| Verbal description only (Quick mode) | workflows/01-prepare.md → 02-decompose.md (lighter) |
| Existing story to modify | workflows/05-modify-story.md |
Ready to start.
Feature: [name]
Mode: [Standard / Quick / Modify / Decompose-only]
Inputs: [list]
Project context: ✅ Loaded / ❌ Not found
Output folder: [path]
Starting from: [workflow name]
Then read the appropriate workflow file.
🚨 Critical Rules
- Never skip workflows — Stages run in order. Each reads the prior stage's output file.
- Always save files — Stories, registry, decomposition saved to workspace. Chat is ephemeral.
- Mark TBDs honestly —
[TBD — requires: {need}] (Route to: {role}). Never fabricate.
- Wait at checkpoints — STOP after decomposition, after each story group, after set review.
- Source accuracy > completeness — An incomplete story that is honest beats a complete story with invented data.
- WHAT not HOW — Design decisions ARE requirements. Technology choices are implementation. Never prescribe implementation.
- Split, don't compress — If a story needs > 6 ACs, it's too big. Split it. Don't merge ACs.
📎 Related Skills
| Situation | Skill to suggest |
|---|
| No requirements doc exists | /generate-requirements or /requirements-pipeline |
| Need an epic first | /generate-epic |
| Validate stories after creation | /validate-user-stories |
| Full pipeline | /story-pipeline |
| Design files need processing | /design-to-context |
INTAKE COMPLETE → Read the appropriate workflow file to begin
