user-story-templates

What this skill does

# 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 → 21-100 users

**10. Interface vs API**: Backend → Frontend → Integration

**Best practice**: Use vertical slicing (complete feature through all layers) vs horizontal slicing (one layer across many features).

**Comprehensive guide**: See `references/story-splitting-guide.md` for detailed examples, anti-patterns, and decision trees.

---

## INVEST Criteria

Good user stories follow the INVEST principles:

**I - Independent**: Can be developed without dependency on other stories
**N - Negotiable**: Details flexible, focuses on outcome not implementation
**V - Valuable**: Delivers clear value to user or business
**E - Estimable**: Team can estimate effort with reasonable confidence
**S - Small**: Fits in one sprint (1-5 days)
**T - Testable**: Clear acceptance criteria that can be verified

### Quick INVEST Check

- [ ] **Independent**: Can this be built without waiting for other stories?
- [ ] **Negotiable**: Does it define outcome, not implementation?
- [ ] **Valuable**: Is the benefit clear and meaningful?
- [ ] **Estimable**: Can the team estimate this confidently?
- [ ] **Small**: Can it be completed in 1-5 days?
- [ ] **Testable**: Are acceptance criteria clear and verifiable?

If a story fails any INVEST criterion, it should be rewritten or split.

**Comprehensive guide**: See `references/invest-criteria-guide.md` for deep dive on each principle with examples, anti-patterns, and fixing strategies.

---

## User Story Best Practices

### Writing Clear Stories

**DO**:

- Focus on user value, not implementation
- Keep stories independent and testable
- Write from user's perspective
- Include clear acceptance criteria
- Size stories for 1-3 days of work

**DON'T**:

- Prescribe implementation ("use React hooks")
- Mix multiple features in one story
- Write from system's perspective
- Skip acceptance criteria
- Create epics disguised as stories

### Good Example

```
As a free trial user
I want to see how many days remain in my trial
So that I can decide when to upgrade

Acceptance Criteria:
- [ ] Days remaining appears in header
- [ ] Warning shows when <7 days remain
- [ ] "Upgrade" CTA appears with countdown
- [ ] Counter updates daily at midnight
```

### Bad Example

```
As the system
I want to implement a counter using React hooks
So that the trial days feature works

[No acceptance criteria]
```

---

## Acceptance Criteria Best Practices

**DO**:

- Make cri