A user story is one requirement written from one user's point of view: "As a [role], I want [action], so that [outcome]." Acceptance criteria are the testable pass/fail conditions that say when that story is done, often written as Given/When/Then. A good set of stories covers every role in your product and every flow, the unhappy ones too, not only the main character on a good day.

TL;DR

  • The template is As a [role], I want [action], so that [outcome]. The role slot is the one teams get wrong.
  • A story is a card, a conversation and a confirmation. The confirmation is the acceptance criteria.
  • Write acceptance criteria as pass/fail checks, one condition per line. Given/When/Then is the clearest format when behaviour depends on a starting state.
  • Most backlogs miss half the product: other roles and unhappy flows. A roles × flows matrix finds them in one sitting.
  • For AI coding tools this matters double. If a flow isn't in the spec, the AI won't build it.
A grid of six user roles by four flows. One cell is lit and reached by a solid line; several other cells are reached only by dashed lines or not at all.

Most user story guides stop at the template. The template is the easy part. The hard part is noticing the stories nobody wrote, and that's where products break in production. This guide covers both, with one example product all the way through: a small team invoicing tool.


What is a user story, and what goes in it?

A user story is a short description of one thing one kind of user needs, and why. It holds a role, an action and an outcome, plus the acceptance criteria that confirm it works.

The point of a story isn't the sentence. It's that the sentence keeps the user in the room while the team decides what to build. One requirement, one user, one benefit. If a story needs "and" to describe what the user wants, it's usually two stories.

A story is deliberately small. It should fit in a sprint, be built by the team without a second spec, and be something you can demo. If you can't imagine showing it working, it's probably a task or an epic in disguise.

What are the 3 C's of a user story?

Card, Conversation, Confirmation. Ron Jeffries named them in 2001: the card is the short written story, the conversation is where the details get worked out, and the confirmation is the tests that prove it's done.

In Ron Jeffries' original note on Card, Conversation, Confirmation, the card is a promise to talk, not the full requirement. That's still the most useful way to read a backlog. The card is short on purpose. The conversation fills in the gaps. And the confirmation, the acceptance criteria, is the part people skip, even though it's the only part a developer or a tester can actually check.

User story vs task vs epic: what's the difference?

An epic is a big piece of user value that's too large for one sprint. A story is one slice of it that a user would notice. A task is a piece of work the team does to build a story, which no user would ever see on its own.

In the invoicing tool, "Get paid by clients" is an epic. "As a team member, I want to send an invoice by email, so that my client can pay it" is a story. "Set up the email template" and "add a Sent status to the database" are tasks. A quick test: if you can't write "As a [role]…" in front of it without lying, it's a task.


What is the user story template?

The standard template is "As a [role], I want [action], so that [outcome]." Fill the role with a real kind of user, the action with what they do, and the outcome with the reason it matters to them.

This is the format Mike Cohn popularised in his writing on user stories, and Atlassian's guide to user stories uses the same three slots. It works because each slot forces a decision:

  • As a [role]. This is the slot people get wrong. "As a user" says nothing. The invoicing tool has members, admins, viewers, a billing owner, invited guests and clients who never log in. Each one needs different things, and each one breaks differently.
  • I want [action]. Something the user does, not something the system does. "I want to send an invoice," not "the system generates a PDF."
  • So that [outcome]. The reason. Skip it and you lose the one line that lets a developer make a sensible call when the spec runs out. If you want to go deeper on outcomes, this slot is close cousin to the job in Jobs to Be Done and outcome-driven innovation.

Copy this and fill it in:

As a [specific role],
I want [an action the user takes],
so that [the outcome they care about].

Acceptance criteria:
- [pass/fail condition]
- [pass/fail condition]
- [what happens when it goes wrong]

What makes a user story good?

A good story passes the INVEST test: Independent, Negotiable, Valuable, Estimable, Small and Testable. If a story fails one of the six, fix the story before the team starts building it.

Bill Wake's INVEST checklist from 2003 is still the shortest quality bar around. In one line each:

  • Independent. It can be built and shipped without waiting on another story.
  • Negotiable. It states the need, not the exact solution, so the team can find a better way.
  • Valuable. A user or the business would notice if it shipped.
  • Estimable. The team understands it well enough to size it.
  • Small. It fits in a sprint, ideally in a few days.
  • Testable. You can write acceptance criteria that pass or fail.

The one I see fail most is Testable. A story without clear criteria can't be finished, only abandoned.


Why do most user stories miss half the product?

Because teams write stories for the main character on the main path and stop there. Every other role, and every flow where something goes wrong or looks different, is left for developers to guess at.

This is the most common mistake I see in teams, and I see it everywhere. The backlog is full of beautiful stories for the main user doing the main thing. As a user, I want to create an invoice. As a user, I want to send it. Lovely. Then the product goes live and the questions start. What does an admin see? What happens to someone who was invited but hasn't signed up yet? What does a read-only teammate get when they click Edit?

The second half of the mistake is the flows. Teams write the happy flow and skip the unhappy ones: the stories for what happens to the user when they run into something else. The payment fails. The link expired. The list is empty because it's their first day. Nobody wrote a story for it, so nobody designed it, so a developer improvised it at 6pm on a Thursday. That's how you end up with a blank screen or an error message that says "Error."

None of this is exotic. It's just unwritten. And the fix isn't more meetings, it's a small table.


How do you find every story? Roles × flows

List every role down the side and every kind of flow across the top: happy, error, blocked and different situation. Each cell is a story you either write or consciously decide to skip.

Here it is for the invoicing tool. Each cell is a one-line story seed, not a finished story. The point is that every cell gets a look:

RoleHappy flowUnhappy: errorUnhappy: blockedDifferent situation
Main userCreate an invoice and send it to a clientSending times out; the draft is kept and I can retryPlan's monthly invoice limit reached; I see why and what to doFirst day, no clients yet; a clear way to add the first one
AdminInvite a teammate and set their roleThe invite email bounces; I see it and can resendTry to remove the last admin; told why it's not allowedA teammate left; reassign their open invoices
Viewer / read-onlyOpen and download any invoiceThe PDF fails to generate; a message, not a blank pageClick Edit; the action is hidden or explained, never a silent failOpen a link to an invoice that was deleted
Billing ownerUpdate the card and see the next chargeCard declined on renewal; notified, with a grace periodTry to downgrade below current usage; see what must change firstSubscription expired; data is read-only, not gone
Invited guest (not signed up yet)Accept the invite and land in the right teamSign-up fails midway; the invite still worksInvite link expired; ask for a new one in one clickAlready has an account under another email
Logged-out visitorOpen a shared invoice link and pay itPayment page times out; no double charge on retryTry to open the app; sent to sign-in, then back to the same pageOpen a link to an invoice that's already paid

Thirty cells, and the happy-flow column is the only one most backlogs fill. The other four columns are where support tickets come from.

How to run it: put the table on a shared screen with a developer and a designer, and go cell by cell. For each one, decide: write the story now, put it in a later release, or skip it on purpose. "Skip on purpose" is a fine answer. "Didn't think of it" is the one you're trying to remove. Roles are also a design question in their own right, and in a custom portal or internal system they're usually the first thing I map, before a single screen.


How do you write acceptance criteria?

Write each criterion as one testable condition that either passes or fails, from the user's point of view. Cover the happy flow, then the errors and edge cases the conversation surfaced.

Good acceptance criteria share a few habits, and Atlassian's guide to acceptance criteria lands in the same place:

  • Pass or fail, nothing in between. "The invoice loads fast" can't fail. "The invoice opens within 2 seconds" can.
  • One condition per line. If a line has "and" in it, a tester will tick half of it.
  • Behaviour, not implementation. Say what the user sees, not which table gets a new column.
  • Include the unhappy flow. At least one criterion for what happens when it goes wrong.

My rule of thumb: if a story has fewer than about three acceptance criteria, the edge cases probably weren't discussed. It's not a law. Some stories really are that simple. But a thin list is usually a sign the conversation, the second C, never happened.

What is the Given/When/Then format?

Given/When/Then writes a criterion as a scenario: Given a starting state, When the user does something, Then this result follows. It comes from behaviour-driven development and reads the same to product, design and engineering.

Dan North introduced it in his 2006 article "Introducing BDD", and Martin Fowler's short explainer on Given When Then describes it as a way of splitting a scenario into its precondition, its action and its expected result. The same structure is the backbone of Gherkin, the language test tools like Cucumber read, so well-written criteria can become automated tests almost as they are.

Here's one story from the invoicing tool, rewritten that way, with the happy scenario and one unhappy one:

Story: As a team member, I want to send an invoice by email,
       so that my client can pay it without me chasing a PDF.

Scenario: Send a finished invoice
  Given I am signed in as a team member
  And a draft invoice has a client email and at least one line item
  When I click "Send"
  Then the client receives the invoice by email
  And the invoice status changes to "Sent"

Scenario: Client email is missing
  Given a draft invoice with no client email
  When I click "Send"
  Then the invoice is not sent
  And I see "Add the client's email to send this invoice"
  And everything I typed in the draft is kept

User story and acceptance criteria examples

Below are three stories from the same invoicing tool: a happy path, a blocked flow and an error. Each comes from a different cell of the roles × flows table, which is exactly the point.

1. Billing owner, happy flow. As a billing owner, I want to update the company card, so that the subscription keeps running without interruption.

Scenario: Update the card
  Given I am signed in as the billing owner
  When I save a new valid card
  Then I see the last four digits of the new card
  And I see the date and amount of the next charge
  And the old card is no longer charged

2. Viewer, blocked. As a read-only viewer, I want to understand why I can't edit an invoice, so that I know who to ask instead of thinking the app is broken.

Scenario: Viewer tries to edit
  Given I am signed in with the Viewer role
  When I open an invoice
  Then I do not see an active Edit button
  And I see "You have view access. Ask an admin to edit this invoice."

3. Logged-out visitor, payment declined. As a client paying from a shared link, I want to know my card was declined and try again, so that I can pay without contacting the sender.

Scenario: Card is declined
  Given I opened a shared invoice link without signing in
  When I pay and my card is declined
  Then I see that the payment did not go through
  And the invoice still shows as unpaid
  And I can try another card on the same page
  And I am not charged twice if I retry

Notice that none of these mention a database, an API or a component. That's what keeps them readable to everyone who needs to agree on them.


How do you write user stories for AI coding tools?

Write them the same way, and be twice as complete. If a flow isn't in the spec, the AI won't build it, so the unhappy flows and the other roles have to be written down, not left to judgment.

A human developer who reads "send an invoice" will often ask "and if the email is missing?". An AI coding tool usually won't. It builds the happy path, confidently, and the empty states, the permission checks and the declined card simply aren't there. Every cell you left blank in the roles × flows table is a cell the AI leaves blank too.

Three habits help:

  • Paste the acceptance criteria, not just the story. Given/When/Then is close to a test, and AI tools are good at building against tests.
  • Name every role up front. Give the tool the list of roles and what each can and can't do before you ask for screens.
  • Build one cell at a time. Happy flow first, then each unhappy cell as its own prompt, so nothing gets folded away.

The stories sit inside a bigger document. The PRD guide covers how to write a PRD that AI coding tools can build from, and if you want the structure handled for you, PRD-in-a-Pocket turns a rough idea into a PRD you can hand to a team or a tool.


FAQ

How many acceptance criteria should a user story have?

There's no fixed number, but three to seven is a common range for a well-sized story. Fewer than about three usually means the edge cases weren't discussed, and more than about ten usually means the story should be split.

Who writes acceptance criteria, the PM or the developers?

The product manager usually drafts them, because they describe what the user needs. Developers and testers then sharpen them in the conversation, since they're the best at spotting the edge cases nobody wrote down.

What is the difference between acceptance criteria and the Definition of Done?

Acceptance criteria are specific to one story and say what that story must do. The Definition of Done applies to every story and sets the shared quality bar, such as tested, reviewed and deployed.

Should every story use Given/When/Then?

No. Use it when the result depends on a starting state, like a role, a plan or an expired link, and use a plain checklist when the criteria are simple facts. Mixing both in one backlog is fine.


Where to go from here

Take the story you're writing today and put it in the roles × flows table. Fill the four columns for the main user, then add one row for each other role. You'll find stories you didn't know were missing, and it takes less time than the bug report would. And if your team needs someone to own this level of product thinking a few days a week, that's what my Fractional PM service is for.

Enjoyed this? Get the next edition in your inbox.

Subscribe