How to Write a User Story (With Examples and Templates)
Most teams can recite the format in ten seconds: as a [user], I want [goal], so that [benefit]. Fewer can actually write one that survives contact with a sprint. Learning how to write a user story that engineers trust and that actually ships the right thing is a different skill than memorizing the template — it’s the difference between a story that generates a useful conversation and one that just generates a ticket number.
This guide covers the format, how to write acceptance criteria that hold up, real examples across different product types, a worked example with the actual trade-offs a team made, common failure patterns and how to fix them, and a template you can use today.
What Is a User Story?
A user story is a short, plain-language description of a feature or functionality written from the perspective of the user who will benefit from it. User stories come from agile software development and are the most common unit of work for product teams using Scrum or Kanban. The Agile Alliance frames the format as a placeholder for a conversation rather than a finished spec: the words on the ticket start the discussion, they don’t end it.
The standard format is:
As a [type of user], I want [some goal] so that [some reason].
Here’s an example:
As a first-time buyer, I want to save my payment details so that I don’t have to re-enter them every time I check out.
The three parts, who, what, and why, keep the team anchored to a real user need rather than a technical requirement. If you’re new to agile workflows in general, our guide on what is agile product management gives useful context for how user stories fit into the broader sprint and backlog process.
Why User Stories Matter
Before agile methodologies became standard, teams wrote product requirements documents (PRDs) that specified exactly what to build, down to the technical implementation. That worked when products changed slowly and requirements were stable. It falls apart in fast-moving product development. For a detailed look at what a PRD covers and when it’s still the right tool, see our guide on what is a PRD and how to write one.
User stories flip the model. Instead of telling engineers what to build, they describe what the user needs to accomplish, and the team, engineers, designers, and PMs together, figures out how. On a 20-person fintech team’s discovery process, the stories that caused the most rework were never badly formatted. They were badly scoped: too big to finish in a sprint, so half of them limped, unfinished, into the next one. Running a lightweight product discovery sprint before writing stories for a new feature area fixes more scoping problems than any template ever will, because the team learns the real shape of the problem before committing words to a ticket.
This shift matters for three reasons. It encourages collaboration: a well-written user story starts a conversation instead of ending one. It keeps focus on value, because every story asks who benefits and why before it asks what to build. And it makes estimation realistic, because small, specific stories are far easier for an engineering team to size than a vague, sprawling requirement.
How to Write a User Story: The Format Explained
The Three Parts
As a [user type]. This is your persona: the specific type of user who will benefit from this feature. Be specific. “As a user” tells you nothing. “As a freelancer who invoices clients monthly” tells you everything you need to empathize with the need.
I want [goal or action]. This describes what the user wants to do. Focus on the action or outcome, not the specific UI implementation. “I want to see a summary of my monthly spending” is better than “I want a pie chart on the dashboard”: the second one has already made a design decision that isn’t yours to make in the ticket.
So that [benefit or reason]. This is the most frequently skipped part, and the most important. The “so that” forces you to articulate the underlying reason behind the feature. It helps the team understand what success looks like, and it often unlocks a better solution than the one the story literally asked for.
User Story Examples
E-commerce
As a returning customer, I want to view my full order history so that I can quickly reorder products I’ve bought before.
As a shopper, I want to filter search results by size and color so that I only see products that are available in what I need.
As a guest user, I want to check out without creating an account so that I can complete my purchase quickly without committing to signing up.
SaaS / B2B
As a team admin, I want to set permission levels for each team member so that I can control who can view, edit, or publish content.
As a project manager, I want to assign tasks to specific team members with due dates so that everyone knows what they’re responsible for and when.
As a billing administrator, I want to download a PDF invoice for each month so that I can reconcile our company’s accounts.
Mobile App
As a commuter, I want to save my most-used routes so that I don’t have to search for directions every morning.
As a user who exercises regularly, I want to set weekly fitness goals so that I can track my progress toward a target.
As a new user, I want to complete a short setup flow when I first open the app so that the experience feels personalized from day one.
Platform / API
As a developer, I want to authenticate via OAuth 2.0 so that I can integrate the API without managing passwords.
As an enterprise customer, I want to export all of my account data in JSON format so that I can migrate to another platform if needed.
A Worked Example: Splitting a Story That Was Too Big
Here’s a real pattern from a 12-person B2B analytics team. The original story read: “As an admin, I want to manage my team’s access so that I can control security.” Everyone nodded in refinement. Nobody could estimate it, because “manage access” could mean anything from a single toggle to a full role-based permissions system.
The team’s actual constraint was a Q3 deadline tied to a single enterprise contract that required just two things: the ability to revoke a user’s access immediately, and a read-only audit log of who had access to what. Everything else, custom roles, granular field-level permissions, approval workflows, was future work nobody had actually asked for yet.
Splitting it into two stories, “As an admin, I want to revoke a user’s access immediately so that a departing employee can’t retain access to customer data” and “As an admin, I want to see a log of who currently has access to what so that I can pass a security audit,” turned one unestimable ticket into two that shipped inside the sprint, satisfied the actual contract requirement, and left the door open for the bigger permissions system later without building it before anyone needed it.
How to Write Acceptance Criteria
A user story by itself doesn’t tell engineers when they’re done. That’s what acceptance criteria are for: a set of conditions that must be true for the story to be considered complete. They define the boundaries of the feature and prevent scope creep.
Teams sometimes treat acceptance criteria as paperwork to fill in after the story’s already in the sprint. Write it after, and it becomes a rubber stamp instead of a shared understanding: the whole point is that everyone agrees on “done” before anyone starts building, not after.
The most common format is Given / When / Then, sometimes called Gherkin syntax. Atlassian’s guide to user stories uses the same structure and is worth bookmarking if your team is standardizing its ticket format for the first time.
- Given [some context or precondition]
- When [the user takes an action]
- Then [the expected outcome]
Acceptance Criteria Example
User Story: As a user, I want to reset my password so that I can regain access to my account if I forget it.
Acceptance Criteria:
- Given I am on the login page, when I click “Forgot password,” then I am taken to the password reset page.
- Given I enter a valid email address, when I submit the form, then I receive a password reset email within 2 minutes.
- Given I click the reset link in my email, when the link is less than 24 hours old, then I am taken to a page where I can set a new password.
- Given I click the reset link in my email, when the link is more than 24 hours old, then I see an error message telling me the link has expired with an option to request a new one.
- Given I enter a new password that meets the requirements, when I submit, then my password is updated and I am automatically logged in.
Tips for Writing Good Acceptance Criteria
Be specific. Vague criteria (“the page should load quickly”) can’t be tested. Specific criteria (“the page should load in under 2 seconds on a standard 4G connection”) can.
Write from the user’s perspective. Acceptance criteria should describe what the user experiences, not how the system implements it internally.
Cover edge cases. What happens when the input is invalid? What if the user is on a slow connection? What if the session has expired?
Aim for 3–8 criteria per story. Fewer than 3 and you’re likely missing edge cases. More than 8 and the story is probably too big and should be split: see the worked example above for what that split actually looks like in practice.
User Story Template
Here’s a reusable template you can adapt:
Story Title: [Short descriptive name]
User Story: As a [specific user type], I want to [accomplish some goal], So that [I receive some benefit/value].
Background / Context: [Optional: any relevant context the team needs to understand the story]
Acceptance Criteria:
- Given [context], when [action], then [outcome].
- Given [context], when [action], then [outcome].
- Given [context], when [action], then [outcome].
Out of Scope: [What this story explicitly does NOT include: helps prevent scope creep]
Dependencies: [Any other stories, APIs, or systems this story depends on]
Priority: [High / Medium / Low] Story Points / Estimate: [Team estimates this in refinement]
What Makes a Good User Story: The INVEST Criteria
The INVEST model, originally developed by Bill Wake, is a useful checklist for evaluating the quality of a user story:
- Independent: can be developed and delivered without depending on other stories
- Negotiable: the details are open to discussion; the story isn’t a contract
- Valuable: delivers real value to the user or business, not just a technical task
- Estimable: the team can roughly size it
- Small: small enough to complete inside one sprint planning cycle, usually 3–5 days of work
- Testable: there are clear criteria for determining when it’s done
If a user story fails any of these, it usually needs to be rewritten or split: the admin-permissions story above failed on Estimable and Small until it got broken apart.
User Stories vs Use Cases vs Tasks
These terms get confused constantly. Here’s how they actually differ:
| User Story | Use Case | Task | |
|---|---|---|---|
| Purpose | Describes what a user wants and why | Describes all possible interactions between user and system | Describes a technical implementation step |
| Format | Plain language, one or two sentences | Formal, detailed, often multi-page | Short technical instruction |
| Audience | Anyone on the team | Engineers, QA, compliance | Engineers only |
| Common in | Modern agile product teams | Enterprise and regulated industries | Sprint backlogs, under a parent story |
| Example | “As a user, I want to reset my password so that I can regain access.” | Multi-step spec covering every login and reset path, including failure states | “Add a password_reset_tokens table to the database” |
A task like “set up the database schema” isn’t a user story: it doesn’t say who benefits or why. Good user stories shouldn’t describe implementation at all; that’s what tasks underneath the story are for.
Where User Stories Break Down (And How to Fix It)
Writing tasks, not stories. “Build the settings page” tells the team what to build, not who benefits or why. Rewrite it as: “As a user, I want to customize my notification preferences so that I only receive alerts that are relevant to me.” If you can’t fill in a real “so that,” you probably don’t have a story yet: you have an idea that needs more discovery first.
Being too vague about the user. “As a user” could describe anyone. The more specific you are, “as a project manager at a company with 50+ employees,” the better the team understands who they’re designing for, and the easier it is to say no to edge cases that persona doesn’t actually have.
Skipping the “so that” clause. Worth pushing back on the common advice that every story needs a fully spelled-out “so that” written into the ticket every time. On a five-person team that talks daily, a story with just enough context that everyone already understands the reason is fine. The formal “so that” starts earning its keep once the team is big enough, or distributed enough, that people build things without ever talking to the person who requested them.
Writing stories that are too large. A story covering an entire feature (“As a user, I want a complete checkout flow”) can’t be delivered in a sprint. Break it down: the admin-permissions example earlier in this guide is exactly this failure mode caught before it cost the team a sprint.
Mixing technical requirements into user stories. “As a user, I want the system to use PostgreSQL so that queries run faster” is a technical requirement wearing a user story’s clothes. Users don’t care about the database. Write: “As a user, I want search results to load in under 2 seconds so that I can find what I need quickly,” and let engineering decide how.
Epics: When User Stories Get Too Big
An epic is a large body of work that can be broken down into smaller user stories. Epics are useful for planning and organizing work at a higher level before you’re ready to write detailed stories.
For example:
Epic: Checkout experience overhaul
User stories under this epic:
- As a guest user, I want to check out without creating an account…
- As a returning user, I want to use saved payment details…
- As a mobile user, I want to complete a purchase in under 3 taps…
- As a user in Europe, I want to pay via iDEAL…
Epics typically live on the roadmap. User stories live in the sprint backlog. Knowing when to keep something at the epic level versus breaking it into stories is really a question about the difference between a roadmap and a backlog: the roadmap communicates direction, the backlog is where stories get specific enough to build.
Try This the Next Time You Write a User Story
Open your backlog and pull the next story you’re about to write. Run it through INVEST before you write a single line of acceptance criteria. If it fails Small or Estimable, split it the way the admin-permissions example did above, by isolating the one constraint that actually matters right now and pushing everything else into a later story you haven’t committed to yet.
The format takes thirty seconds to learn. Writing stories your team can actually estimate, build, and ship inside a sprint takes doing this on purpose, on every ticket, until it’s a habit instead of a checklist.
References
- Cohn, Mike. User Stories Applied: For Agile Software Development. Addison-Wesley, 2004.
- Agile Alliance. “User Stories.” agilealliance.org
- Atlassian. “User stories | Examples and Template.” atlassian.com
- Wake, Bill. “INVEST in Good Stories, and SMART Tasks.” XP123, 2003.
