User story template and examples
A user story is a short description of something a user needs, told from their side: who they are, what they want to do, and why. The usual format is “As a [user], I want [action], so that [outcome]”. With acceptance criteria it becomes something a team can build and check. Below is a template to copy, a version for Jira, examples for software, the INVEST checklist, ways to split a story, and how a story differs from a use case, an epic and a task.
The “as a, I want, so that” text is normally just a summary of who/what/why, and the ticket will include acceptance criteria detailing the changes to be implemented.
— Hacker News, May 2023
User story format
As a [type of user],
I want [an action or a capability],
so that [the outcome they get].
The template “originated with agile coach Rachel Davies at a UK company, Connextra, in the early 2000s” (Mountain Goat Software). Each part does a job:
| Part | What it says | What goes wrong without it |
|---|---|---|
| As a … | Who needs it | Everyone builds for a different imagined user |
| I want … | What they want to do | The story turns into a task: “add a button” |
| So that … | Why they want it | Nobody can suggest a better way to get the same outcome |
The “so that” is the easiest part to skip, and the one that lets the team push back. An old Hacker News example: “As a user, I should be able to mark my favorite posts, so that I can find them again.” Then: “It may turn out that users don’t need to find old posts, or would prefer to search instead of looking through an old list” (Hacker News, 2009).
The sentence is only the start. Ron Jeffries described a story as three things — card, conversation and confirmation — where the card “has just enough text to identify the requirement, and to remind everyone what the story is” (ronjeffries.com, 2001). The confirmation is the acceptance criteria.
User story template
Copy it into Jira, Azure DevOps, Linear or a document. Square brackets are yours to fill in.
USER STORY
ID: [US-n]
Title: [verb + object, e.g. "Pay an
open invoice"]
As a [type of user],
I want [action],
so that [outcome].
Acceptance criteria
1. Given [context], when [action], then
[result].
2. Given [context], when [action], then
[result].
Out of scope
- [what this story does not do]
Notes
Requirement: [FR-n or BR-n it builds]
Designs: [link]
Questions: [open question, and who
answers it]
Estimate: [points or days]
User story template for Jira
Jira’s story has a summary and a description. Put the title in the summary and this in the description:
STORY
As a [type of user], I want [action], so
that [outcome].
ACCEPTANCE CRITERIA
1. Given [context], when [action], then
[result].
2. Given [context], when [action], then
[result].
OUT OF SCOPE
- [ ]
LINKS
Requirement: [FR-n] Designs: [link]
If your team has added an acceptance criteria field, move the criteria there. When the stories are also where the requirements live, see managing requirements in Jira for what that takes.
User story examples for software development
Four stories from a customer portal, with their acceptance criteria.
Sign in:
As a customer, I want to sign in with my
email address and password, so that I can
see my company's account.
1. Given a registered email and the right
password, when I sign in, then I see my
account overview.
2. Given the wrong password 5 times in
10 minutes, when I try again, then
sign-in is blocked for 15 minutes and I
am told why.
3. Given I forgot my password, when I
choose "Reset password", then I get a
reset link by email.
Pay an invoice:
As a customer, I want to pay an open
invoice by card, so that I don't have to
arrange a bank transfer.
1. Given an open invoice, when I pay it by
card and the bank approves, then the
invoice shows "Paid" with today's date.
2. Given the bank declines, then the
invoice stays open and I see the bank's
reason.
Download an invoice:
As a customer, I want to download any
invoice as a PDF, so that I can file it
with my accounts.
1. Given any invoice of my company, when I
choose "Download", then I get a PDF
that matches the invoice on screen.
Invite a colleague:
As an account owner, I want to invite
colleagues by email, so that they can pay
invoices without my login.
1. Given I invite an email address, then
that person gets an invitation valid
for 7 days.
2. Given an invited colleague signs up,
then they can see and pay invoices, but
not invite others.
More acceptance criteria formats and examples, including for APIs, are on the acceptance criteria template page.
What makes a good user story: INVEST
Bill Wake’s checklist, from 2003:
| Letter | A good story is | Ask |
|---|---|---|
| I | Independent | Can it be built and released without waiting for another story? |
| N | Negotiable | Is the “how” still open to a conversation? |
| V | Valuable | Would the user notice, and care, if it shipped alone? |
| E | Estimable | Does the team know enough to size it? |
| S | Small | Does it fit in one sprint, with room to spare? |
| T | Testable | Could someone who did not write it tell when it is done? |
How to split a user story
A story too big for one sprint needs splitting. Mike Cohn’s SPIDR names five ways to cut it:
| Split by | What it means | “Pay an invoice”, split |
|---|---|---|
| Spike | Research first, then the story | Find out which card provider fits, then build |
| Paths | One path through the flow at a time | Card first; bank transfer in a later story |
| Interfaces | One interface or device at a time | Web first; the mobile app later |
| Data | Simpler data first | One invoice at a time; paying several at once later |
| Rules | Relax a rule, add it back later | Full payment only; partial payments later |
Each part should still be a story a user would notice — not “build the database table”.
User story vs use case, epic, task and requirement
| Item | What it is | Example |
|---|---|---|
| User story | One need of one user, small enough for a sprint | Pay an open invoice by card |
| Epic | A large need, split into stories | Online payments |
| Task | A piece of work inside a story, for the team | Add the payment provider’s SDK |
| Use case | Every step of an interaction, with the main and alternative flows | Customer pays invoice: steps 1–9, declined card, timeout |
| Requirement | A statement of what the system must do, kept in a specification | FR-014: A signed-in customer can pay any open invoice of their company by card |
| Job story | Like a user story, but starting from the situation: “When …, I want to …, so I can …” | When an invoice is due today, I want to pay it in one step, so I can avoid a late fee |
On some projects stories and requirements live side by side: the requirement in the functional specification, the stories in the backlog, each story naming the requirement it builds. A traceability matrix keeps the two connected.
User story vs requirement: a story says who wants something and why; a requirement says what the system must do, precisely enough to test. Not everyone sees much difference. The accepted answer to a Stack Exchange question on it calls “user story” “just a fancy term for ‘functional requirement’”, and adds: “What user stories almost never capture, in my experience, are non-functional requirements like performance and security” (Stack Exchange, 2013). Another answer goes back to Ron Jeffries’ card, conversation and confirmation: before the conversation, a story “is not a requirement but a promise to hold a conversation” (Stack Exchange, 2013).
In the portal, the story is “As a customer, I want to pay an open invoice by card, so that I don’t have to arrange a bank transfer.” The requirements are FR-014 (who can pay what), its acceptance criteria, and NFR-007 (how fast). The story is enough while the team that wrote it builds it in one sprint. Write the requirement too when someone outside the team has to sign it off, when it will outlive the sprint, or when an AI coding agent builds from it. More on how the two fit with the other kinds in types of requirements.
Common mistakes
- “As a developer, I want …” A story about the system, not a user. Write it as a task inside a real story.
- No “so that”. Without the why, nobody can suggest a simpler way.
- No acceptance criteria. The story cannot be checked, so “done” becomes an argument — and the definition of done cannot settle it alone.
- A story per screen element. “Add a field” is a task; the story is what the user can now do.
- Too big. If the team cannot size it, split it.
- The format for its own sake. Not everyone likes it: one commenter would rather have “a table of features with a column for the target user type” (Hacker News, September 2026). The sentence matters less than the who, the why and the criteria.
User stories for AI coding agents
Some developers now hand a story straight to a coding agent: “Most of my prompts are “implement <issue-id>”. The issue has a user story and acceptance criteria that the LLM uses to write a plan and ultimately produce code” (Hacker News, September 2026).
Agents also write stories, and not always well. Birgitta Böckeler asked Kiro to fix a small bug:
The requirements document turned this small bug into 4 “user stories” with a total of 16 acceptance criteria, including gems like “User story: As a developer, I want the transformation function to handle edge cases gracefully, so that the system remains robust when new category formats are introduced.”
— martinfowler.com, October 2025
For an agent, the acceptance criteria matter more than the sentence: they are what it can check its work against. Keep stories user-facing, keep each one small, and put the boundaries — what not to change — in the story or in the spec it belongs to.
Where Specroot fits
This is the problem Specroot works on: stories that point to the requirement they build, so that when the requirement changes, the stories built from it say so. Specroot for agencies and consultancies.
Read next
- Acceptance criteria template: Given/When/Then examples — Free acceptance criteria templates (Given/When/Then and checklist), with examples for user stories and APIs, and how they differ from the definition of done.
- Product requirements document (PRD) template — A free PRD template with a filled-in example, a prd.md version for Claude Code and other AI coding agents, and how a PRD differs from a BRD and a spec.
- Requirements traceability matrix (RTM): template and example — A free requirements traceability matrix template for Excel or Google Sheets, a filled-in example, forward and backward traceability, and RTMs in Jira and agile.