A user story names who needs a capability, what they need to do, and why it matters. Acceptance criteria define observable conditions that must be true for the story to be accepted. The story starts discussion; the criteria preserve agreed behavior across normal, boundary, permission, error, and recovery cases.
Who this is for: Product managers, designers, engineers, and quality specialists refining product work into shared, testable behavior.
- Keep one story centered on a coherent user goal that can be discussed and demonstrated end to end.
- Write acceptance criteria as observable examples or rules rather than implementation tasks or subjective adjectives.
- Refine criteria collaboratively and include consequential failures, permissions, accessibility, and data effects.
Find the user goal
Start from the person and situation, not the interface control. 'As an account owner, I want to review pending invitations so I can remove mistaken recipients before access begins' communicates goal and value. 'As a user, I want an invitation page' names an output while leaving the behavior and consequence unclear.
Use the story as a conversation anchor, not a complete requirements container. Link evidence and broader context, then discuss workflow, alternatives, and constraints with the team. Split stories when users can receive independent value or when one part carries substantially different risk. Do not split only by technical layer if no slice can be demonstrated meaningfully.
Choose a criteria format
Rule-oriented criteria work for stable policies: only workspace owners can revoke invitations. Example-oriented criteria use given, when, and then to show context, action, and observable result. Select the format that communicates behavior precisely. Mixing both is acceptable when a broad rule needs concrete boundary examples.
Avoid criteria such as 'works correctly,' 'loads quickly,' or 'is intuitive.' Replace them with a measurable threshold, testable state, or planned usability evaluation. Do not prescribe database tables or component names unless implementation is itself a binding constraint. The criteria should survive reasonable changes in design and architecture.
Cover meaningful states
Write the ordinary success path first, then inspect eligibility, permissions, empty state, duplicates, invalid input, interruption, timeout, concurrency, and recovery. Select cases by consequence and likelihood rather than producing an exhaustive theoretical list. Clarify what the user sees and what data changes when an operation partially fails.
Include nonfunctional needs when they shape acceptance: keyboard access, screen-reader names, localization, response time, audit records, security, privacy, or reliability. Link specialist standards and identify reviewers. A story can be functionally correct while still excluding users or exposing data, so those conditions cannot remain implicit.
Refine and verify together
Product, design, engineering, analytics, and quality partners should examine criteria before work begins. Ask what each term means, which source governs rules, how the behavior will be tested, and what telemetry is needed. Examples often reveal that teammates imagined different actors, timing, or error handling behind the same short story.
During review, demonstrate each criterion and record defects or deliberate changes. Acceptance means the agreed capability behaves as specified; it does not prove the product outcome. After release, assess real use and value separately. Update shared documentation when behavior changes so old criteria do not become misleading product records.
Specify canceling a pending invitation
Workspace owners sometimes invite the wrong email address and need to prevent access before acceptance.
- Write the owner goal and value without naming a specific button or page layout.
- Add the success case: a pending invitation is revoked and its link no longer grants access.
- Define permission behavior for administrators, ordinary members, and removed owners.
- Cover already accepted, already expired, duplicate action, network failure, audit record, and accessible confirmation states.
- Review examples with engineering and quality partners, then demonstrate them before release.
Story refinement card
Use this card during backlog refinement to reveal assumptions before delivery begins.
- Story: specific actor, situation, desired capability, customer value, and linked evidence.
- Success: starting state, action, visible result, persisted data effect, and completion signal.
- Boundaries: eligibility, permission, empty, invalid, duplicate, concurrent, interrupted, and recovery cases.
- Quality: accessibility, performance, privacy, security, reliability, localization, and audit requirements.
- Verification: test owner, examples, analytics, specialist approval, demonstration, and behavior documentation.
Common mistakes
- Using a generic actor called user when permissions and goals differ among roles.
- Writing acceptance criteria as engineering subtasks that do not describe observable product behavior.
- Covering only the happy path and discovering irreversible or permission failures after implementation.
Try one
Improve the story 'As a user, I want search' and provide criteria that would expose ambiguity.
A good response chooses a real actor and job, such as a support agent finding an account by verified email to answer a caller. Criteria define eligible records, exact and partial matching, no-result behavior, permissions, response threshold, keyboard use, sensitive-field display, and unavailable-service recovery. The answer should avoid prescribing a search library or treating subjective usefulness as acceptance.
Sources
- Atlassian user stories guideOfficial guidance on user-centered stories and acceptance criteria.
- Atlassian product requirements guideOfficial guidance on collaborative, concise, and testable product requirements.