The user story format — "As a [user], I want [capability], so that [benefit]" — is one of the most recognized patterns in software development. It is also one of the most misused.
Bad user stories are everywhere: stories with no acceptance criteria, stories so vague that engineers have to guess what to build, stories so prescriptive that they dictate implementation. This guide covers how to write stories that actually result in shipped, working software.
Table of Contents
What Is a User Story?
A user story is a short, informal description of a feature told from the perspective of the person who needs it. It is not a specification. It is a placeholder for a conversation.
Ron Jeffries described the three C's of user stories:
The card is intentionally incomplete. It exists to trigger a conversation, not to replace one. If your stories are 3 pages long with UML diagrams, they are not stories — they are specs pretending to be stories.
The User Story Format
The standard format:
As a [type of user],
I want [capability or action],
so that [benefit or value].Each part serves a specific purpose:
Why the "So That" Matters
The benefit clause does three things:
Beyond the Template
The three-part format is a starting point, not a constraint. Some teams add:
The format matters less than the content. A well-written story without the template is better than a poorly written story that follows it perfectly.
Writing Acceptance Criteria
Acceptance criteria define what "done" means for a user story. Without them, the PM and the engineer may have completely different pictures of the finished feature.
The Given/When/Then Format
Given [a precondition],
When [an action occurs],
Then [an expected result].Example: User Story with Acceptance Criteria
Story: As a team admin, I want to invite members by email, so that I can onboard my team without IT support.
Acceptance criteria:
How Many Acceptance Criteria?
What Not to Include in Acceptance Criteria
Acceptance criteria describe what the system does, not how it is built or what it looks like. See the acceptance criteria glossary entry for more.
The INVEST Criteria
Bill Wake created the INVEST acronym to describe well-written user stories. Use it as a checklist.
I — Independent
Stories should not depend on each other. If Story B cannot be built until Story A is complete, they are coupled. Rewrite them so either can be built first, or combine them.
Bad: "As a user, I want to see my profile photo" (depends on "upload profile photo")
Better: "As a user, I want to upload and display my profile photo" (single story) or decouple them so display works with a default avatar.
N — Negotiable
Stories are not contracts. The details should be open for discussion during sprint planning and development. If a PM writes a story that prescribes every pixel and API endpoint, it is not negotiable — it is a spec.
E — Estimable
The team needs enough information to estimate the effort. If they cannot estimate, the story needs more conversation or research. A common solution: create a spike (a time-boxed research task) to resolve unknowns before writing the full story.
S — Small
A story should be completable within a single sprint. If it takes more than one sprint, it is an epic and needs to be split.
Rule of thumb: Most stories should take 1-5 days of engineering work. If it is bigger, split it.
T — Testable
If you cannot write a test for it, you cannot verify it is done. Vague stories ("improve the user experience") are not testable. Specific stories ("reduce checkout steps from 5 to 3") are.
Story Splitting
The most common problem with user stories is that they are too big. Large stories are hard to estimate, hard to build in one sprint, and hard to test. Here are practical splitting techniques.
Split by Workflow Step
Original: As a customer, I want to purchase a product online.
Split:
Split by User Type
Original: As a user, I want to manage my account settings.
Split:
Split by Input/Output
Original: As a user, I want to export my data.
Split:
Split by Business Rules
Original: As a user, I want to search for products.
Split:
Split by Happy Path vs Edge Cases
Original: As a user, I want to reset my password.
Split:
The "Walking Skeleton" Approach
For complex features, build the thinnest possible end-to-end version first, then add depth:
Real Examples: Good vs Bad
Example 1: Dashboard Feature
Bad: "As a user, I want a dashboard."
Why it is bad: No user type, no specific capability, no benefit, no acceptance criteria. An engineer could build anything from a blank page to a NASA mission control center.
Good: "As a sales manager, I want to see my team's pipeline value by stage on a dashboard, so that I can identify stalled deals in my weekly forecast meeting."
Acceptance criteria:
Example 2: Notification Feature
Bad: "As a user, I want notifications so that I know what is happening."
Why it is bad: What kind of notifications? For what events? Through what channel?
Good: "As a project member, I want to receive an in-app notification when someone assigns me a task, so that I do not miss new work assigned to me."
Acceptance criteria:
Example 3: Search Feature
Bad: "Build search functionality."
Why it is bad: Not a user story at all — no user, no benefit, no scope.
Good: "As a support agent, I want to search customer tickets by keyword and status, so that I can find related issues when handling a customer call."
Acceptance criteria:
User Story Maps
Story mapping, created by Jeff Patton, is a visual technique for organizing stories into a big-picture view.
How It Works
Why Story Maps Work
When to Use Story Mapping
Common Mistakes
Mistake 1: Stories Without the "So That"
The benefit clause is the most important part of a user story, and the most frequently omitted. Without it, engineers do not know why they are building something, which leads to technically correct but practically useless implementations.
Mistake 2: Technical Stories Disguised as User Stories
"As a developer, I want to refactor the authentication module, so that the code is cleaner." This is a technical task, not a user story. User stories describe value to end users. Technical work is valid and important, but it should be tracked differently — as tech debt items or engineering enablers.
If there is a user-facing reason for the refactoring, use that: "As a user, I want the login page to load in under 1 second, so that I can access my account quickly." The refactoring is the implementation — the story is the user need.
Mistake 3: Epic-Sized Stories
"As a user, I want to manage my account." This is an epic containing dozens of stories. If a story cannot be completed in a single sprint, it needs to be split.
Mistake 4: Stories That Prescribe Solutions
"As a user, I want a blue button in the top-right corner that opens a modal with a dropdown menu." This is a design spec, not a user story. Stories describe the need; the team decides the solution.
Better: "As a user, I want to quickly switch between my workspaces, so that I can manage multiple projects without logging out." Let the designer decide whether it is a dropdown, a sidebar, or a keyboard shortcut.
Mistake 5: Skipping the Definition of Done
A story is not done when the engineer says "it works on my machine." Define done for your team: code reviewed, tests passing, deployed to staging, acceptance criteria verified, documentation updated.
Mistake 6: Writing All Stories Upfront
You do not need 200 stories on day one. Write detailed stories for the next 1-2 sprints. Keep future work as rough epics or themes. Details emerge through discovery and conversation — writing them too early means rewriting them later.