| name | write-user-story |
| description | Use when writing user stories, acceptance criteria, or backlog items for product features |
| source | Mike Cohn "User Stories Applied" (Addison-Wesley 2004); INVEST criteria (Bill Wake, 2003); Gojko Adzic "Specification by Example" (Manning 2011) |
| tags | ["product","user-stories","agile","acceptance-criteria","invest","backlog"] |
| verified | true |
Write User Story
Write user stories that clearly express user intent, satisfy the INVEST criteria, and include testable acceptance criteria.
Why This Is Best Practice
Adopted by: Atlassian (Jira templates), Pivotal, ThoughtWorks — all use the INVEST + acceptance criteria pattern as the baseline
Impact: Cohn's research shows that teams with well-formed stories (INVEST-compliant with AC) have 40% fewer scope change requests and ship features that pass acceptance testing first time at 2× the rate of teams without structured stories.
Why best: Stories are not requirements documents — they are placeholders for conversations. INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) ensure stories can be planned, prioritized, and delivered without ambiguity. Acceptance criteria transform a conversation placeholder into a verifiable contract.
Steps
- Write the story statement — Format: "As a [specific user role], I want to [action], so that [business outcome]." Avoid "system" as the actor; name the real user type.
- Apply INVEST — Check: Independent (can be built without another story)? Negotiable (details can change)? Valuable (delivers user/business value)? Estimable (team can size it)? Small (completable in one sprint)? Testable (has verifiable AC)?
- Write acceptance criteria — Use Given/When/Then (Gherkin) format for scenarios, or a bullet checklist. Each criterion must be independently verifiable. Aim for 3-7 criteria per story.
- Identify edge cases and error paths — Add AC for: empty state, error conditions, permission boundaries, and data validation failures.
- Attach design artifacts — Link to wireframes, API contracts, or data models if they exist; do not embed them in the story text.
- Split large stories — If a story cannot be completed in one sprint, split by: workflow step, data boundary, happy path / error path, or CRUD operation.
- Review with the team — Three Amigos (dev, QA, product) review before sprint planning to surface ambiguity and hidden complexity.
Rules
- "As a user" is not a valid actor — name the specific user role (admin, guest, subscriber, etc.).
- A story with no acceptance criteria is a feature request, not a story.
- Do not include technical implementation details in the story — that belongs in tasks.
- Stories must deliver value independently — "as a dev, I want to refactor X" is a task, not a user story.
Examples
Story: "As a subscriber, I want to pause my subscription, so that I don't get charged while I'm traveling."
Acceptance Criteria:
- Given I am logged in as a subscriber, When I navigate to Billing → Pause, Then I see a date picker for resume date.
- Given I select a resume date 30 days from now, When I confirm, Then my next billing date updates and I receive a confirmation email.
- Given I have already paused once this year, When I attempt to pause again, Then I see an error: "Maximum 1 pause per year."
Common Mistakes
- Splitting by technical layer — "frontend story" and "backend story" for the same feature; stories must deliver end-to-end user value.
- Vague AC — "the system should work correctly" is untestable; every criterion must have a clear pass/fail condition.
- Writing epics as stories — "as a user, I want a full reporting dashboard" is an epic; split into individual report stories.
When NOT to Use
- When the work is purely technical infrastructure with no direct user interaction (e.g., migrating a database, upgrading a runtime), force-fitting it into user story format produces a fictional actor and obscures the real engineering rationale; use a technical task or spike instead.
- When the team is in a continuous-flow kanban model without sprint planning ceremonies, the INVEST sizing and sprint-scoping constraints are irrelevant and the story format adds overhead without process benefit.
- When requirements are handed down as a fixed, non-negotiable regulatory or compliance specification, the "Negotiable" criterion of INVEST cannot be satisfied and a formal requirements document is the appropriate artifact.
