write-user-story

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.

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

1. 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.
2. 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)?
3. 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.
4. Identify edge cases and error paths — Add AC for: empty state, error conditions, permission boundaries, and data validation failures.
5. Attach design artifacts — Link to wireframes, API contracts, or data models if they exist; do not embed them in the story text.
6. 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.
7. 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.