Generate User Stories

Generate User Stories — Entry Orchestrator

⚠️ Execution Discipline

You are now operating under this skill's instructions exclusively. BEFORE generating ANY output, verify:

1. Have I read the workflow file for this step?
2. Have I completed ALL prior stages per the state file?
3. 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 map
  • story-registry.md — cumulative cross-story tracker
  • Story-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

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

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:

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

1. Never skip workflows — Stages run in order. Each reads the prior stage's output file.
2. Always save files — Stories, registry, decomposition saved to workspace. Chat is ephemeral.
3. Mark TBDs honestly — [TBD — requires: {need}] (Route to: {role}). Never fabricate.
4. Wait at checkpoints — STOP after decomposition, after each story group, after set review.
5. Source accuracy > completeness — An incomplete story that is honest beats a complete story with invented data.
6. WHAT not HOW — Design decisions ARE requirements. Technology choices are implementation. Never prescribe implementation.
7. Split, don't compress — If a story needs > 6 ACs, it's too big. Split it. Don't merge ACs.

📎 Related Skills

INTAKE COMPLETE → Read the appropriate workflow file to begin