Skip to main content

User Story Template

Template​

# User Story: [Story Title]

## Description
As a [type of user]
I want to [perform some action]
So that [achieve some goal]

## Acceptance Criteria
```gherkin
Given [some context]
When [some action is taken]
Then [expected outcome]

Given [some context]
When [some action is taken]
Then [expected outcome]

Technical Notes​

  • Required APIs:
  • Database changes:
  • Security considerations:
  • Performance requirements:

Dependencies​

  • Dependent on:
  • Required by:

Effort Estimate​

Story Points: [1, 2, 3, 5, 8, 13]

Test Cases​

Scenario: [Test scenario name]
  Given [setup]
  When [action]
  Then [verification]

Design Assets​

  • Mockups:
  • Prototypes:
  • Style guides:

## Usage Guide

### When to Use
- Feature planning
- Sprint planning
- Task breakdown
- Acceptance criteria definition

### Best Practices

1. **User Story Description**
   - Focus on user value
   - Use clear, simple language
   - Follow the As/I want/So that format
   - Keep it concise

2. **Acceptance Criteria**
   - Use Gherkin format
   - Cover all scenarios
   - Include edge cases
   - Be specific and measurable

3. **Technical Notes**
   - List all technical requirements
   - Include security considerations
   - Note performance requirements
   - Document API needs

4. **Dependencies**
   - List all blockers
   - Note related stories
   - Include external dependencies
   - Track status

### Examples

#### Feature Story
```md
# User Story: User Dark Mode Toggle

## Description
As a user
I want to toggle between light and dark mode
So that I can comfortably use the app in different lighting conditions

## Acceptance Criteria
```gherkin
Given I am logged in
When I click the theme toggle button
Then the app theme should switch between light and dark mode

Given I have selected dark mode
When I refresh the page
Then the dark mode setting should persist

Given I am using dark mode
When I log in on another device
Then my theme preference should be applied

Technical Notes​

  • Required APIs: User preferences API
  • Database changes: Add theme preference to user model
  • Security considerations: None
  • Performance requirements: Theme switch should be instant

Dependencies​

  • Dependent on: User preferences service
  • Required by: None

Effort Estimate​

Story Points: 5

Test Cases​

Scenario: Theme persistence
  Given user selects dark mode
  When user refreshes the page
  Then dark mode should remain active

Design Assets​

  • Mockups: figma.com/dark-mode-designs
  • Prototypes: figma.com/dark-mode-prototype
  • Style guides: Dark mode color palette

#### Bug Story
```md
# User Story: Fix Session Timeout

## Description
As a user
I want my session to remain active while I'm using the app
So that I don't lose my work unexpectedly

## Acceptance Criteria
```gherkin
Given I am logged in
When I remain active on the site
Then my session should not timeout

Given my session is about to expire
When I am actively using the site
Then the session should automatically refresh

Given my session has expired
When I try to perform an action
Then I should be prompted to login again

Technical Notes​

  • Required APIs: Auth refresh token API
  • Security considerations: Token rotation
  • Performance requirements: Silent refresh

Dependencies​

  • Dependent on: Auth service
  • Required by: All authenticated features

Effort Estimate​

Story Points: 3

Test Cases​

Scenario: Active session refresh
  Given user session is about to expire
  When user is active on the site
  Then session should silently refresh