How to Write User Stories That Engineers Will Actually Build
Learn to write user stories that engineering teams love. Includes INVEST framework, 10 real examples from Stripe and Linear, common mistakes, and free template.
:::tip[Quick Answer] A great user story follows the INVEST framework (Independent, Negotiable, Valuable, Estimable, Small, Testable) and uses the format: “As a [user], I want to [action], so that [benefit].” The key is focusing on why (user value) rather than how (implementation). Good user stories enable conversation, not replace it. :::
What Makes a Good User Story?
User stories are the bridge between product vision and engineering execution. A poorly written user story leads to:
- Engineering building the wrong thing
- Endless clarification meetings
- Scope creep and missed deadlines
- Frustrated teams on both sides
A well-written user story:
- Provides clarity without constraining creativity
- Focuses on user value, not implementation details
- Invites collaboration and questions
- Can be estimated and tested
The INVEST Framework for User Stories
The INVEST framework, created by Bill Wake in 2003, remains the gold standard for evaluating user stories:
Independent
Stories should be self-contained and not depend on other stories being completed first.
❌ Bad: “Update user settings page UI” (depends on which settings were added) ✅ Good: “As a user, I want to change my email address in settings, so I can update my contact info”
Negotiable
Stories are not contracts. They should invite discussion about implementation.
❌ Bad: “Build a dropdown menu with 15px padding and #3B82F6 color for the sort options” ✅ Good: “As a user, I want to sort my project list by date or priority, so I can find what I need faster”
Valuable
Every story should deliver value to a user (customer, admin, or internal stakeholder).
❌ Bad: “Refactor the authentication module to use JWT tokens” ✅ Good: “As a user, I want to stay logged in for 30 days, so I don’t have to sign in every visit”
Estimable
Engineers should be able to estimate the effort required.
❌ Bad: “Improve app performance” (too vague) ✅ Good: “As a power user, I want the dashboard to load in under 2 seconds, so I don’t lose time waiting”
Small
Stories should be completable within one sprint (1-2 weeks).
❌ Bad: “As a user, I want a complete analytics dashboard with charts, filters, exports, and custom reports” ✅ Good: “As a user, I want to see a line chart of my signups over the last 30 days”
Testable
There should be clear acceptance criteria to verify completion.
❌ Bad: “As a user, I want a better onboarding experience” ✅ Good: “As a new user, I want to complete account setup in 3 steps or less, so I reach value faster”
The User Story Format That Works
The classic format remains effective:
“As a [user type], I want to [action], so that [benefit].”
Breaking it down:
- As a [user type]: Be specific. “User” is too generic. Use “free user,” “admin,” “team owner,” “first-time visitor”
- I want to [action]: What does the user want to do? Use active verbs
- So that [benefit]: Why does this matter? What value does it provide?
The “so that” clause is the most important part. It forces you to articulate why we’re building this.
10 Real User Story Examples from Top Companies
1. Stripe — Payment Setup
“As a developer, I want to integrate Stripe payments in less than 10 minutes, so I can start accepting payments without reading 50 pages of documentation.”
Why it works: Specific user (developer), measurable outcome (10 minutes), clear value (save time).
2. Linear — Issue Creation
“As a product manager, I want to create issues directly from Slack messages, so I don’t lose context switching between tools.”
Why it works: Addresses workflow friction, clear benefit (no context loss).
3. Notion — Template Sharing
“As a team admin, I want to share internal templates with one click, so new team members can start with our processes immediately.”
Why it works: Reduces onboarding friction, clear value to both admin and new users.
4. Figma — Version History
“As a designer, I want to restore any previous version of my design, so I can experiment freely without fear of losing work.”
Why it works: Removes a barrier to creativity, clear emotional benefit.
5. Vercel — Deployment Preview
“As a developer, I want to preview my changes in a production-like environment before merging, so I catch bugs before customers do.”
Why it works: Risk mitigation, clear consequence (avoid customer bugs).
6. Slack — Do Not Disturb
“As a remote worker, I want to set do-not-disturb hours automatically, so I don’t get notifications at 2am from teammates in other time zones.”
Why it works: Solves a real pain point, measurable outcome.
7. GitHub — Pull Request Templates
“As a repository owner, I want to require a PR template for all contributions, so contributors provide consistent information upfront.”
Why it works: Scales collaboration, clear benefit (consistency).
8. Airtable — View Permissions
“As a team owner, I want to share specific views (not entire bases) with clients, so they see only what’s relevant to them.”
Why it works: Privacy + simplicity, clear stakeholder benefit.
9. Loom — Video Trimming
“As a video creator, I want to trim my recording before sharing, so I don’t waste viewers’ time with mistakes.”
Why it works: Respects viewer’s time, clear quality benefit.
10. Superhuman — Keyboard Shortcuts
“As a power user, I want to navigate my entire inbox with keyboard shortcuts, so I can process 100 emails in 10 minutes instead of 30.”
Why it works: Measurable time savings, targets power users specifically.
Common User Story Mistakes (and How to Fix Them)
Mistake 1: Writing Technical Tasks as User Stories
❌ “As a developer, I want to migrate the database from MySQL to PostgreSQL”
This is a technical task, not a user story. Users don’t care about database technology.
✅ “As an admin, I want to export user data in under 5 seconds, so I can respond to data requests quickly”
Mistake 2: Skipping the “So That” Clause
❌ “As a user, I want to filter projects by status”
Without “so that,” there’s no clear value. Maybe this isn’t even needed!
✅ “As a project manager, I want to filter projects by status, so I can see what’s blocked and needs my attention”
Mistake 3: Making Stories Too Large
❌ “As a user, I want a complete onboarding flow with welcome email, tutorial videos, product tour, and progress tracking”
This is an epic (multiple stories). Break it down.
✅ Four stories:
- “As a new user, I want to receive a welcome email with next steps”
- “As a new user, I want to watch a 90-second product tour”
- “As a new user, I want to see my setup progress (0-100%)”
- “As a new user, I want to skip onboarding if I’m already familiar”
Mistake 4: Describing Implementation Instead of Outcome
❌ “As a user, I want a red button that says ‘Delete’ in the top-right corner”
This constrains design and doesn’t explain why.
✅ “As a user, I want to delete my account permanently, so I can remove my data when I stop using the service”
Mistake 5: Using “User” for Every Story
❌ “As a user, I want to approve pending team members”
Not all users can do this. Be specific.
✅ “As a team owner, I want to approve pending members, so I control who has access to our workspace”
How to Write Acceptance Criteria
Every user story needs acceptance criteria (AC) — the conditions that must be met for the story to be “done.”
Format:
Given [context]
When [action]
Then [expected result]Example story: “As a user, I want to reset my password, so I can regain access if I forget it”
Acceptance criteria:
Given I'm on the login page
When I click "Forgot password?" and enter my email
Then I receive a password reset link within 2 minutes
Given I click the password reset link
When I enter a new password (min 8 characters)
Then I'm logged in automatically and see a success message
Given the password reset link is older than 24 hours
When I try to use it
Then I see an error: "This link has expired" and can request a new oneUser Stories vs. Requirements: What’s the Difference?
| Aspect | User Stories | Requirements |
|---|---|---|
| Focus | User value | System behavior |
| Format | ”As a [user], I want…" | "The system shall…” |
| Flexibility | Invites discussion | Detailed specification |
| Detail Level | High-level | Low-level |
| Best For | Agile teams | Waterfall, regulated industries |
User stories work best when:
- Teams iterate frequently
- Requirements may change based on feedback
- Cross-functional collaboration is possible
Traditional requirements work best when:
- Scope must be locked (contracts, compliance)
- Teams are distributed across time zones
- Implementation is outsourced
You can use both: user stories for planning, detailed requirements for complex features.
Free User Story Template
Basic Template:
As a [specific user type],
I want to [action],
So that [benefit].
Acceptance Criteria:
- [ ] [Specific, testable condition]
- [ ] [Another condition]
- [ ] [Edge case or error handling]
Priority: [High/Medium/Low]
Estimate: [Story points or hours]Advanced Template (for complex features):
Title: [Short, descriptive name]
User Story:
As a [user type],
I want to [action],
So that [benefit].
Context:
- Why now: [Business justification]
- Who asked: [Stakeholder or customer feedback]
- Impact: [Expected outcome, metrics]
Acceptance Criteria:
Given [context],
When [action],
Then [expected result].
Out of Scope (for this story):
- [Related features NOT included here]
Design Notes:
- [Links to Figma, mockups]
Technical Notes:
- [API endpoints, data models, dependencies]How to Run a User Story Writing Workshop
Want to level up your team’s user story skills? Run a 90-minute workshop:
Agenda:
- Intro (15 min): Share INVEST framework, show good vs. bad examples
- Practice Round 1 (20 min): Each person writes 3 stories for the same feature
- Review (15 min): Read stories aloud, vote on best, discuss why
- Practice Round 2 (20 min): Write stories for a feature from your backlog
- Critique (15 min): Pair up, review each other’s stories using INVEST
- Wrap (5 min): Each person commits to rewriting one existing story by EOD
Materials needed:
- Post-its or virtual whiteboard (Miro, FigJam)
- INVEST checklist handout
- 3-5 features to practice on
- Voting method (dots, thumbs up, etc.)
Tools for Managing User Stories
| Tool | Best For | Pricing |
|---|---|---|
| Rock n Roll | PM tools + roadmap planning | Free tier |
| Linear | Engineering-focused teams | $8/user/month |
| Jira | Enterprise Agile teams | $7.75/user/month |
| Asana | Marketing + product crossover | Free tier available |
| Notion | Flexible, customizable workflows | Free tier available |
| Shortcut | Fast-moving startups | $8.50/user/month |
Frequently Asked Questions
How long should a user story be?
A user story should be 1-3 sentences plus acceptance criteria. If you need a paragraph to explain it, it’s either too complex (break it down) or you’re writing a requirement instead of a story. The story card is a “promise for a conversation,” not a complete specification.
What’s the difference between a user story and an epic?
An epic is a large feature that takes multiple sprints to build (e.g., “Build a complete analytics dashboard”). User stories are small, completable pieces of that epic (e.g., “As a user, I want to see daily signups in a line chart”). Break epics into stories before planning sprints.
Should every user story follow the “As a… I want… So that…” format?
The format is a helpful guide, but not a strict rule. Some teams use “Job Stories” format: “When [situation], I want to [action], so I can [outcome].” Others write stories as problem statements. The key is clarity, user focus, and testability — not rigid adherence to a template.
How many acceptance criteria should each story have?
Typically 3-5 acceptance criteria per story. Too few (0-1) means the story is too vague. Too many (10+) means the story is too large and should be split. Each AC should be independently testable and represent a meaningful condition for “done.”
Who writes user stories — PMs or engineers?
Product managers typically write initial user stories during roadmap planning, but the best teams refine them together. Engineers often spot edge cases, technical constraints, or opportunities for simplification. User stories should be collaborative, not handed down as edicts.
Summary: The User Story Checklist
Before adding a story to your backlog, verify:
- ✅ INVEST compliant: Independent, Negotiable, Valuable, Estimable, Small, Testable
- ✅ User-focused: Written from a specific user’s perspective (not “the system”)
- ✅ Value-driven: Clear “so that” clause explaining why this matters
- ✅ Testable: 3-5 acceptance criteria that define “done”
- ✅ Sized right: Completable in one sprint (1-2 weeks)
- ✅ Conversation starter: Invites questions, doesn’t answer every detail
Great user stories accelerate teams. Bad ones slow everyone down. Invest time in writing good ones.
Try Rock-n-Roll FreeRelated Posts
Turn JTBD insights into product specs
Rock-n-Roll takes your customer research and turns it into structured documentation: strategy briefs, solution blueprints, and builder-ready implementation plans.
Start your free project