User Story Acceptance Criteria Template

Start from the agreed spec, not a blank backlog: stories work best when they divide up scope people have already agreed. If there isn't a spec yet, write a PRD first. Then turn each requirement into one or more stories, each a change a user would notice.

Use the familiar template: "As a [type of user], I want [an action] so that [a benefit]." Mountain Goat Software, Mike Cohn's agile training firm, calls "As a user, I want reports so that I can see information" vague in all three parts¹. Name a real role, one action and the reason it matters.

Take the reason from evidence, such as support tickets or themes from your user interviews, not from the feature request. If nobody can say why a story matters, ask whether it belongs in this release.

The Scrum Guide says backlog items that can be done within one sprint are ready for selection² at sprint planning. Humanizing Work, a firm that trains agile teams, uses a tighter rule. By the time a story reaches the top of the backlog, 6 to 10 like it should fit in one sprint³.

Bill Wake's 2003 INVEST checklist says a good story is independent, negotiable, valuable, estimable, small and testable. He compares a story to a layered cake and advises slicing vertically through the layers⁴. A finished database layer is worth little to a customer with no screen to use it.

Humanizing Work's guide names nine ways to split a story. Here are five, applied to a feature for inviting teammates:

• Workflow steps: invite by email now, and add admin approval as its own story
• Operations: "manage invites" hides send, resend and revoke
• Business rules: invite any address first, then limit invites to your domain
• Data entry: type one address now, and upload a list of addresses later
• A spike, as a last resort: when nobody knows how to build it, time-box the research

The Given, When, Then format comes from Dan North, who came up with behavior-driven development, and business analyst Chris Matts. North described their template in 2006: Given some initial context, When an event occurs, Then ensure some outcomes⁵. Each criterion sets the scene, does one thing and checks the result.

Write every criterion so it can fail. Use real values, not placeholders, because "3 of 5 seats in use" exposes disagreements that "some seats" hides. Cucumber, an open-source testing tool, recommends 3 to 5 steps per example⁶ in its Gherkin reference. It also says the Then should check something you can observe, like a screen or a message, not a record buried in a database.

Surprises tend to hide in states the spec never mentions. For each story, check these and write down what should happen:

• It already exists: the invited address already has an account
• It ran out: the link expired, or every seat is taken
• It was withdrawn: the invite was revoked, or the admin lost their rights
• Two people at once: two admins invite the same address
• It failed halfway: the invite email bounced

North's article applies the same thinking to a cash withdrawal at an ATM. Beyond an account in credit, he lists an account overdrawn past its limit and a dispenser with insufficient cash⁵, each a scenario of its own. If the flow has many branches, draw a user flow and journey map first.

Some cases have no agreed answer yet. Cucumber project lead Matt Wynne puts it plainly: when the outcome is unclear, you don't have an example, you have a question⁷. Write the question down and move on.

His Example Mapping session puts a developer, a tester and a product person around one story for about 25 minutes. They write its rules, examples and questions on cards of different colors. Lots of question cards mean there is still much to learn. Lots of rule cards mean the story is big and may need slicing.

Give each question an owner and the date you need an answer, and hold the estimate for every story it affects. As Wake puts it, it's hard to estimate a story we don't understand⁴.

Standards that apply to every story, such as code review, tests, accessibility checks and updated help pages, belong in the team's definition of done, written once. The Scrum Guide describes it as the state finished work must reach to meet the product's quality measures. Work that misses it can't be released².

Acceptance criteria are the other half: what makes this one story correct. Copying team standards onto every story only buries the criteria that matter.

Working from a long spec? Paste it into the box at the top of this page, and River drafts the stories, the criteria and the list of open questions for you to review.