mhylle/user-story

User Story

Overview

This skill generates hierarchical user stories (epics → features → tasks) with formal Given/When/Then acceptance criteria. It works in two modes: consuming brainstorm output for rich context, or standalone with its own clarification phase. Task-level stories share format with create-plan phases for seamless handoff.

Workflow Position: brainstorm → (ADRs + user stories) → create-plan → implement-plan

Related ADRs:

• ADR-0003: One file per epic with INDEX.md
• ADR-0004: Hierarchical numbering (EPIC-NN.F-NN.T-NN)
• ADR-0005: Shared format contract with create-plan
• ADR-0006: Upstream of create-plan, parallel to ADRs

Initial Response

When this skill is invoked, respond:

"I'm ready to help you define user stories. I can work from a brainstorm document or start fresh. Let me check for recent brainstorms, or you can describe the feature/system you want to define requirements for."

Workflow (5 Phases)

Phase 1: Input Detection

Determine the input mode and gather initial context.

Step 1: Check for explicit brainstorm path

If the user passed a file path argument ($0):

Read($0)  # Read the brainstorm file

→ Proceed to Phase 2 with brainstorm content as context.

Step 2: Auto-scan for recent brainstorms

If no argument provided, scan for recent brainstorm files:

Glob("docs/brainstorms/*.md")

| Scenario | Action | |----------|--------| | Recent brainstorms found (last 7 days) | Present list and ask: "I found these recent brainstorms. Would you like to base user stories on one of them, or start fresh?" | | No recent brainstorms | Proceed to standalone mode (Phase 3) | | User selects a brainstorm | Read the file, proceed to Phase 2 | | User wants to start fresh | Proceed to Phase 3 |

Step 3: Check for existing user stories

Always check for existing stories to avoid duplication:

Read("docs/user-stories/INDEX.md")  # If it exists

If existing stories overlap with the current scope, note them and ask whether to extend, revise, or create new epics.

Phase 2: Context Gathering

Gather all relevant context before generating stories.

Always do:

1. Read brainstorm output (if available from Phase 1)

   • Extract: goals, components, risks, decisions, suggested scope
   • Identify user types/personas mentioned

2. Read existing ADRs for architectural context:

   Read("docs/decisions/INDEX.md")
   # Then Quick Reference (first 10 lines) of relevant ADRs
   

3. Read existing user stories INDEX (if it exists):

   Read("docs/user-stories/INDEX.md")
   

When project context is detected (user mentions codebase, files, modules):

4. Research codebase for existing patterns:

   Task(subagent_type="codebase-locator",
        prompt="Find all files related to [feature area]")
   Task(subagent_type="codebase-analyzer",
        prompt="Analyze how [related functionality] is implemented")
   

After gathering context, present a summary:

## Context Summary
- **Source**: [Brainstorm file / Standalone input]
- **Existing Stories**: [None / EPIC-01, EPIC-02...]
- **Relevant ADRs**: [ADR-NNNN, ...]
- **Codebase Context**: [Key files and patterns found]

Then proceed to Phase 3 if standalone, or Phase 4 if brainstorm input provides sufficient context.

Phase 3: Clarification (Standalone Mode)

When working without brainstorm input, use targeted Socratic questioning to understand requirements.

Round 1: Users & Goals (ask 2-3 questions)

| Category | Example Questions | |----------|------------------| | Users/Personas | "Who are the primary users of this system/feature?" | | | "Are there different user roles with different needs?" | | Core Goals | "What is the primary problem being solved?" | | | "What does success look like for the user?" |

Round 2: Scope & Constraints (ask 2-3 questions)

| Category | Example Questions | |----------|------------------| | Scope | "What is explicitly in scope for this work?" | | | "What should be considered out of scope?" | | Constraints | "Are there technical constraints to be aware of?" | | | "Are there existing systems this must integrate with?" |

Round 3: Success Criteria (ask 2-3 questions)

| Category | Example Questions | |----------|------------------| | Acceptance | "How will you know this feature is working correctly?" | | | "What are the key scenarios that must work?" | | Edge Cases | "What error cases or edge cases concern you most?" | | | "What happens when things go wrong?" |

Continuation Protocol:

• After each round, offer: "I have more questions if you'd like to continue refining, or we can move to story generation. Your call."
• Continue until user signals readiness
• Do NOT rush -- thorough clarification produces better stories

Phase 4: Story Generation

Generate hierarchical user stories from the gathered context.

Step 1: Identify Epics

Extract high-level goals/capabilities from the input. Each epic represents a major user-facing capability.

Epic format:
  ID: EPIC-NN
  Title: [Capability name]
  Description: As a [user type], I want [goal] so that [benefit]
  Status: Draft

Limits: If more than 5-7 epics emerge, discuss with the user which to prioritize for this session.

Step 2: Decompose into Features

For each epic, identify 2-5 features that compose it:

Feature format:
  ID: EPIC-NN.F-NN
  Title: [Feature name]
  Description: As a [user type], I want [specific capability] so that [benefit]

Limit: Max 5 features per epic. If more emerge, suggest splitting the epic.

Step 3: Decompose into Tasks

For each feature, identify 2-5 implementable tasks:

Task format (shared with create-plan phases):
  ID: EPIC-NN.F-NN.T-NN
  Title: [Task name]

  **Objective**: [What this task accomplishes]

  **Acceptance Criteria**:
  - **Given** [precondition]
    **When** [action]
    **Then** [expected result]

  **Tasks** (tests first, then implementation):
  - [ ] Write tests: [test file] covering [scenarios]
  - [ ] Implement: [file] to make tests pass
  - [ ] Verify: [specific check or command]

  **Exit Conditions**:
  Build Verification:
  - [ ] [build/lint/typecheck commands]

  Runtime Verification:
  - [ ] [start command, no errors]

  Functional Verification:
  - [ ] [test commands, specific checks]

Limit: Max 5 tasks per feature. If more emerge, suggest splitting the feature.

Step 4: Review with User

Before writing output, present the hierarchy for review:

## Story Hierarchy Preview

### EPIC-01: [Title]
  - EPIC-01.F-01: [Feature title] (N tasks)
  - EPIC-01.F-02: [Feature title] (N tasks)

### EPIC-02: [Title]
  - EPIC-02.F-01: [Feature title] (N tasks)

Total: N epics, N features, N tasks

Does this decomposition look right? Any adjustments before I write the detailed stories?

Wait for user confirmation before proceeding to output.

Phase 5: Output

Write the user story files following the conventions from ADR-0003 and ADR-0004.

Step 1: Create directory (if needed)

mkdir -p docs/user-stories

Step 2: Write epic files

For each epic, write a file using the template from references/story-template.md:

File: docs/user-stories/EPIC-NN-slug.md

See references/story-template.md for the complete format.

Step 3: Create/update INDEX.md

Write/update docs/user-stories/INDEX.md using the template from references/index-template.md.

Step 4: Report summary

After writing all files, present:

## User Stories Created

| File | Epic | Features | Tasks |
|------|------|----------|-------|
| [EPIC-01-slug.md](docs/user-stories/EPIC-01-slug.md) | [Title] | N | N |
| [EPIC-02-slug.md](docs/user-stories/EPIC-02-slug.md) | [Title] | N | N |

**Index**: docs/user-stories/INDEX.md

## Recommended Next Steps
1. Review and refine acceptance criteria
2. Create ADRs for any architectural decisions identified (`/adr`)
3. Create implementation plan from these stories (`/create-plan`)

Shared Format Contract

Task-level stories share structure with create-plan phases per ADR-0005.

See references/shared-format.md for the exact contract.

Shared base (both user stories and plan phases):

• Objective
• Tasks (tests first, then implementation)
• Exit Conditions (build/runtime/functional verification)

User stories add:

• Acceptance Criteria (Given/When/Then)
• Story description (As a [user], I want [goal] so that [benefit])

Quality Checklist

Before finalizing output, verify:

Structure:

• [ ] All epics have Quick Reference blocks
• [ ] Hierarchical numbering is consistent (EPIC-NN.F-NN.T-NN)
• [ ] Max 5 features per epic, max 5 tasks per feature
• [ ] INDEX.md is created/updated

Content:

• [ ] Every story has "As a [user], I want [goal] so that [benefit]"
• [ ] Every task has at least one Given/When/Then acceptance criterion
• [ ] Task-level format matches shared format contract (Objective, Tasks, Exit Conditions)
• [ ] Exit conditions cover build, runtime, and functional verification
• [ ] Status is set (Draft for new stories)

Context:

• [ ] Brainstorm input was fully consumed (if applicable)
• [ ] Existing stories were checked for overlap
• [ ] Relevant ADRs are referenced
• [ ] User confirmed the hierarchy before output was written

Best Practices

Writing Good User Stories

1. Users, not systems: Write from the user's perspective, not the system's
2. Independent: Each feature should be independently deliverable where possible
3. Testable: Every story should have clear, verifiable acceptance criteria
4. Small enough: If a task has more than 3-4 Given/When/Then criteria, consider splitting it

Writing Good Acceptance Criteria

1. Specific: "Given a user with admin role" not "Given a user"
2. Observable: Focus on visible outcomes, not internal state
3. Complete: Cover the happy path AND key error/edge cases
4. Independent: Each criterion tests one behavior

Hierarchy Guidelines

| Level | Represents | Timeframe | Example | |-------|-----------|-----------|---------| | Epic | Major user capability | Weeks-months | "User Authentication" | | Feature | Deliverable functionality | Days-weeks | "Password Reset Flow" | | Task | Single implementable unit | Hours-days | "Email Validation on Reset Form" |

Integration with Create-Plan

When create-plan is invoked after user stories:

• Each task-level story can become a plan phase
• Given/When/Then criteria become exit conditions
• The shared format means no translation step is needed
• Reference story IDs in the plan for traceability

Resources

references/

• story-template.md - Epic file format and story structure at each level
• index-template.md - INDEX.md template for user stories directory
• shared-format.md - Shared format contract between user stories and create-plan