Skip to content
Trevin Nimaladasa

TEMPLATESJIRA · US

User Story

A short statement of user need in "As a / I want / so that" form with Given-When-Then acceptance criteria.

Paste the blank into the ticket description and overwrite the [brackets].

  1. 01Summary

    Name the outcome for the user in one line. Start with the user, not the system. If you can't say it in under 15 words, the story is two stories.

    [User] can [do something] [where / how]

    Example

    Customers can reset their password in the mobile app

  2. 02User Story

    Fill each slot with something specific. "User" is never a type. The benefit is what changes for them, not what the feature does.

    As a **[type of user]**, I want **[goal]** so that **[benefit]**.

    Example

    As a customer locked out of my account, I want to reset my password inside the app so that I can get back in without contacting support.

  3. 03Context

    Say why this is needed now, and link what the reader will want open next to it: the requirement, the epic, the designs, the decision.

    - Why now: [trigger or deadline]
- Links: [Requirement], [Epic], [designs], [decision]

    Example

    • Why now: password resets are 31% of support contacts and cost roughly 9 minutes each
    • Links: REQ-212, EPIC-41 Modernise customer onboarding, Figma "Reset flow v3"

  4. 04Assumptions / Notes

    Write down what you're treating as true but haven't confirmed. Each line is something that could be wrong and change the story.

    - [Assumption you haven't confirmed]

    Example

    • Customers have access to the email address on file
    • The identity provider supports reset tokens with a 30 minute expiry

  5. 05Acceptance Criteria

    One Given / When / Then per behaviour. Include at least one negative or edge case. Each line must be testable by someone who wasn't in the room.

    - Given [context], when [action], then [expected result].
- Given [context], when [action], then [expected result].
- Edge case: given [context], when [action], then [expected result].

    Example

    • Given a registered customer on the sign-in screen, when they tap "Forgot password" and enter their email, then a reset link is sent within 60 seconds.
    • Given a valid reset link, when the customer sets a new password that meets policy, then they are signed in and the old password stops working.
    • Edge case: given a reset link older than 30 minutes, when the customer opens it, then they see "This link has expired" and a button to request a new one.

  6. 06Non-functional Requirements

    Only keep the lines that apply, and give each a number you could test. Delete the rest. An empty heading reads as "not considered".

    - Performance: [target]
- Security / access: [rule]
- Accessibility: [standard]
- Logging / audit: [what is recorded]

    Example

    • Performance: reset email queued in under 5 seconds at p95
    • Security / access: reset tokens are single-use and rate-limited to 5 requests per hour per account
    • Accessibility: all screens meet WCAG 2.2 AA with VoiceOver and TalkBack
    • Logging / audit: every reset request and completion is logged with timestamp and device, never the token

  7. 07Dependencies

    Name the team, system or decision this waits on, and the date you need it by.

    - [Team or system], needed by [date]

    Example

    • Identity team: reset-token endpoint, needed by 14 Nov
    • Comms: approved email wording, needed by 21 Nov

  8. 08Out of Scope

    List the things a reasonable person would assume are included and aren't. This is the line that stops scope creep in review.

    - [Adjacent thing this story does not cover]

    Example

    • Resetting via SMS
    • Changing the password while signed in
    • The web version of the flow

  9. 09Definition of Done (DoD)

    Start from your team's standard and delete what doesn't apply. Add anything specific to this story. Every line should be something you can point at.

    - [ ] Acceptance criteria met and evidenced (screenshots, logs, test results).
- [ ] Test cases updated or created.
- [ ] Documentation updated (if needed).
- [ ] Stakeholder review completed (if required).
- [ ] Linked work items updated and closed as appropriate.

    Example

    • Acceptance criteria met, with a screen recording attached for each.
    • TC-118 to TC-124 written and passing in UAT.
    • Support runbook updated with the new reset steps.
    • Security sign-off on token handling.
    • REQ-212 marked delivered; EPIC-41 progress updated.