/user-story-templates

name: user-story-templates
description: "User story templates with acceptance criteria, story splitting, and INVEST criteria. Use when writing user stories, defining acceptance criteria, splitting large stories, or refining a backlog for sprint planning. Trigger on: 'write user stories for this feature', 'acceptance criteria', 'Given-When-Then', 'split this epic into stories', 'INVEST criteria'."

User Story Templates

Comprehensive templates and frameworks for writing effective user stories with clear acceptance criteria, enabling agile development teams to deliver value incrementally.

What is a User Story?

A user story is a concise description of a feature from the end-user's perspective. It follows the format: "As a [user], I want [goal], so that [benefit]."

**Purpose**:

• Communicate requirements from user perspective
• Enable incremental delivery
• Facilitate conversation and collaboration
• Support estimation and planning
• Guide testing and acceptance

When to Use This Skill

**Auto-loaded by agents**:

• `requirements-engineer` - For user story formats, epic breakdown, and spike stories

**Use when you need**:

• Breaking down features into user stories
• Writing acceptance criteria
• Planning sprints and iterations
• Communicating requirements to development teams
• Refining product backlogs
• Splitting large stories
• Validating story quality with INVEST criteria
• Estimating and prioritizing work

---

User Story Format

Basic Template

As a [user type/persona]
I want to [action/goal]
So that [benefit/value]

**Example**:

As a small business owner
I want to export my invoices as PDF
So that I can send professional-looking invoices to clients

Three Key Components

**1. User Type/Persona** (Who)

• Specific user segment or role
• Good: "free trial user", "team administrator", "mobile app user"
• Bad: "user" (too vague), "the system" (not a user)

**2. Action/Goal** (What)

• What the user wants to accomplish
• Good: "filter search results by date range", "receive email notifications"
• Bad: "have a button" (describes UI), "use the API" (describes implementation)

**3. Benefit/Value** (Why)

• Why the user wants this, what value it provides
• Good: "so that I can quickly find relevant information"
• Bad: "so that it works" (not a benefit), omitting "so that" entirely

For detailed guidance on each component, see `assets/basic-user-story-template.md`.

---

Ready-to-Use Templates

We provide copy-paste-ready templates for common story types:

Feature Stories

**Use for**: New features, enhancements, user-facing work **Template**: `assets/feature-story-template.md`

Includes:

• Full user story format
• Acceptance criteria checklist
• Definition of Done
• Story points and priority
• Dependencies tracking

---

Bug Fix Stories

**Use for**: Defects, regressions, user-reported issues **Template**: `assets/bug-fix-story-template.md`

Includes:

• Current vs expected behavior
• Steps to reproduce
• Environment details
• Severity levels
• Impact assessment

---

Technical Debt Stories

**Use for**: Refactoring, code improvements, infrastructure work **Template**: `assets/technical-debt-story-template.md`

Includes:

• Technical context
• Proposed solution
• Impact on performance/maintainability/scalability
• Risk assessment
• Business value justification

---

Spike/Research Stories

**Use for**: Time-boxed investigation, POCs, research tasks **Template**: `assets/spike-research-story-template.md`

Includes:

• Research questions
• Time box
• Deliverables
• Acceptance criteria for knowledge gained
• Next steps identification

---

Epic Breakdown

**Use for**: Breaking large initiatives into manageable stories **Template**: `assets/epic-breakdown-template.md`

Includes:

• Epic goal and value proposition
• Story sequencing
• Definition of Done (epic level)
• Timeline and dependencies
• Risk mitigation

---

Acceptance Criteria

Acceptance criteria define when a story is "done." Use one of three formats:

1. GIVEN-WHEN-THEN (BDD Style)

Best for: Complex workflows, state-dependent behavior, testing focus

GIVEN [precondition/context]
WHEN [action/event]
THEN [expected outcome]

**Example**:

GIVEN I'm on the login page
WHEN I enter valid email and password
THEN I'm redirected to my dashboard

2. Checklist Format

Best for: Simple features, quick validation, straightforward requirements

Acceptance Criteria:
- [ ] [Observable outcome 1]
- [ ] [Observable outcome 2]
- [ ] [Observable outcome 3]

**Example**:

- [ ] Export button appears on data table
- [ ] Clicking export generates CSV file
- [ ] CSV includes all visible columns
- [ ] CSV filename includes current date
- [ ] Export completes within 5 seconds for up to 10K rows

3. Rule-Based Format (MoSCoW)

Best for: Variable scope, prioritization needed, time-constrained sprints

Must: [Critical requirements]
Should: [Important but not critical]
May: [Nice to have]

**Comprehensive guide**: See `references/invest-criteria-guide.md` for deep dive on writing testable, specific criteria including error states, edge cases, and performance requirements.

---

Story Splitting

Large stories (>5 days or >8 points) should be split into smaller, deliverable pieces.

Common Splitting Patterns

**1. Workflow Steps**: Sequential process steps (e.g., checkout: cart → shipping → payment → confirmation)

**2. CRUD Operations**: Create → Read → Update → Delete

**3. User Roles**: Admin → Manager → Employee → Guest

**4. Business Rules**: Different variations of logic (e.g., discount types: percentage, fixed amount, BOGO)

**5. Simple to Complex**: MVP → Advanced features (progressive enhancement)

**6. Happy Path vs Edge Cases**: Success scenarios → Error handling

**7. Data Variations**: Different formats, sizes, types

**8. Platform/Device**: Desktop → Tablet → Mobile

**9. Performance Tiers**: 1-5 users → 6-20 users → 2