Skip to content

User Story

At a glance

  • Purpose: Express a requirement as a user's need, with the conditions that make it acceptable — small enough to be built and verified in one iteration.
  • Use it when: Writing agile backlog items. Use a specification document instead when the requirement is a safety rule, a regulation, or an interface with an external system.
  • Owner: The product owner writes them; the team splits them and adds the acceptance criteria.
  • Related: Module 04 · Lab 14

How to use this template

  1. Use the role–capability–benefit form, but do not let it become a ritual. If "so that…" adds nothing, the story is a task and should be labelled as one.
  2. Add acceptance criteria in Given/When/Then form. These are what testing is written against and what makes the story verifiable.
  3. Split any story that cannot finish in one iteration. Splitting by workflow step, by rule variation, by data type, or by happy-path-then-exceptions are all legitimate; splitting by architectural layer is usually not, because no slice alone delivers value.
  4. List the exceptions — the messages, states, and error cases the team will otherwise ask about halfway through.
  5. Record the story's origin so the requirement is traceable, and add it to the requirements traceability matrix.

Field descriptions

Field What goes in it Watch out for
ID Stable reference Renumbering after splitting
Story As a [role], I want [capability], so that [benefit] Technical tasks in story clothing
Context Anything the team needs but the story omits Assumptions left implicit
Acceptance criteria Given/When/Then, one behaviour each Criteria that cannot fail
Exceptions Error states, limits, messages Only the happy path described
Out of scope What this story deliberately excludes Silent assumptions about boundaries
Estimate Relative size, agreed by the team Numbers imposed on the team
Origin Source requirement or stakeholder No traceability
Need by A date only if a real dependency requires it Arbitrary deadlines smuggled in

Blank template

# User Story — [ID]

> As a **[role]**, I want **[capability]**, so that **[benefit]**.

| | |
| --- | --- |
| **Estimate** | [n points] |
| **Origin** | [Requirement ID / stakeholder / workshop] |
| **Priority** | [Order, or MoSCoW class] |
| **Need by** | [Date, only with a stated reason] |

## Context

[What the team needs to know: the current behaviour, the surrounding workflow, the relevant rule.]

## Acceptance criteria

| # | Given | When | Then |
| --- | --- | --- | --- |
| 1 | [Precondition] | [Action] | [Observable outcome] |
| 2 | | | |

## Exceptions

| Situation | Expected behaviour |
| --- | --- |
| [Invalid input / limit reached / service unavailable] | [Message or state] |

## Out of scope

- [Related behaviour deliberately excluded, and where it is handled instead]

## Notes and decisions

| Date | Note | Source |
| --- | --- | --- |

Worked example

Two versions of the same request from Lab 14, invented for teaching:

Weak:

As a user, I want to upload files, so that I can submit my application.

Workable:

As an applicant, I want to upload one supporting document with my application, so that I do not have to deliver it in person.

# Given When Then
1 I am on the document step and no file is attached I attach a PDF under 5 MB The file appears with its name and size, and I can continue
2 A file is attached I submit the application The document is stored against my application and retrievable by staff
3 A file is attached I replace it before submitting Only the replacement is stored
Situation Expected behaviour
File is not a PDF Message naming the accepted format; the application is not blocked
File exceeds 5 MB Message stating the limit and the current file size
Upload fails mid-way Retry offered; the rest of the form is preserved

The weak version cannot fail a test, has no role or benefit, and leaves the file type, size, and storage behaviour for the team to guess. The workable version is testable, bounded, and — crucially — says what happens on the three paths that were previously unstated.

Common mistakes

  • The role is "user". If the role carries no information, no one can judge the benefit.
  • Acceptance criteria that cannot fail. "Works properly" verifies nothing.
  • Only the happy path. Most defects live in the exceptions, which are also the cheapest place to discover them.
  • Stories sliced by architecture. "Create the database schema" delivers nothing a user can see and cannot be evaluated.
  • Prescribing the interface. Wireframes help; a story that dictates markup is a design, not a story.
  • An estimate imposed on the team. Estimation is the team's, and relative sizing depends on their judgement.
  • Using stories for everything. Regulatory rules and safety requirements need precise specification and should be traced, not narrated.