Stop 05 · Requirements & DocumentationTopics · 2/9

User Stories & Acceptance Criteria

In short

A user story says who needs something and why. Acceptance criteria say exactly how you'll know it's done. Together they stop "that's not what I meant" at the end.

A user story frames a requirement from the user's perspective ('As a [user], I want [goal], so that [reason]'); acceptance criteria define exactly when that story is considered done.

The purple blob at a bakery counter talks with a baker about a chocolate cake on a stand.

Think of it like this

Ordering a birthday cake

"As a son, I want an eggless chocolate cake, so Mum can enjoy her birthday." That's the story. "Ready by 6 pm Saturday, 1 kg, says Happy Birthday Ma" is the checklist the baker and you both use to judge it.

Watch it happen

Refining one story together

PM / Analyst

Engineer

Tester

As a student, reset pwd

1/5The story: as a student, I want to reset my password with an OTP, so I can log back in quickly.

The big ideas

What you need to know

As a… I want… so that…

Who, what, and why. The "so that" part is the most important; it explains the value.

Criteria are testable

Each criterion is a pass or fail check. "Fast" isn't testable. "Loads in under 2 seconds" is.

A story is a conversation

The card is a reminder to talk. Details get filled in when the team discusses it together.

Small enough to finish

A story should fit in one sprint. If it doesn't, split it into thinner slices of value.

See it in code

Walk through the code

gherkin

1Feature: Reset password with OTP2  Scenario: Student resets password with a valid OTP3    Given I am on the "Forgot password" screen4    And I have entered my registered phone number5    When I enter the correct 6-digit OTP within 5 minutes6    Then I can set a new password7    And I am logged in automatically

1/4Name the feature and one specific scenario. Add more scenarios for errors and edge cases.

Acceptance criteria in Given/When/Then form. Tools like Cucumber can run scenarios like this as automated tests.

Save yourself the pain

Common mistakes

Oops

Writing "As a user, I want a button" with no reason.

Do this instead

Name a specific user and the value: "As a returning student, I want…, so that…".

Oops

Leaving acceptance criteria vague, like "works properly".

Do this instead

Write checks anyone can test the same way, including error and edge cases.

Your mission

Write three stories with criteria

~30 min

Quick check

Which is the best acceptance criterion?

Go deeper

1Write 5 user stories for a feature, each with 2-3 acceptance criteria.
2Practice the Gherkin 'Given-When-Then' format for acceptance criteria.
3Learn why vague acceptance criteria cause the most PM-engineer friction.