User Stories
A short, simple description of a software feature told from the perspective of the end user, capturing who needs it, what they need, and why.
What it is
User Stories follow the format "As a [type of user], I want [some goal], so that [some reason]." They are intentionally brief—details are added through conversation and acceptance criteria. A good story follows INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable.
Unlike traditional requirements documents, user stories are conversation starters. They exist to capture the essence of a need without prescribing exactly how to build it. The team discusses the story, asks questions, and agrees on acceptance criteria before work begins.
When to use it
Use user stories for all product backlog items in agile teams. They work best when:
- The team is delivering software iteratively
- Stakeholders need to understand priorities without reading technical specs
- Requirements are expected to evolve as the team learns
- You need to split large initiatives into deliverable chunks
Benefits: user-centric focus, facilitates conversation, flexible to change, understandable by non-technical stakeholders.
Key concepts
The Format
The classic user story template has three parts:
| Component | Purpose | Example |
|---|---|---|
| As a | Identifies the user or role | As a registered customer |
| I want | States the goal or action | I want to reset my password |
| So that | Explains the benefit or motivation | So that I can regain access to my account |
INVEST Criteria
Bill Wake's INVEST mnemonic helps you write stories that are ready for development:
| Letter | Meaning | What it means in practice |
|---|---|---|
| I | Independent | Can be developed and delivered without heavy dependency on other stories |
| N | Negotiable | Open to discussion and refinement—not a fixed contract |
| V | Valuable | Delivers clear value to the user or business |
| E | Estimable | The team can size it with reasonable confidence |
| S | Small | Fits within a single sprint or iteration |
| T | Testable | Has clear acceptance criteria that can be verified |
Acceptance Criteria
Acceptance criteria turn a vague story into a testable deliverable. They describe the specific conditions that must be met for the story to be considered complete. A common format is Given-When-Then:
Given I am on the login page
When I enter a valid email and click "Forgot Password"
Then I should receive a reset link within 5 minutes
Story Splitting
When a story is too large, split it using one of these patterns:
- By workflow step — split across stages (e.g., draft, review, publish)
- By business rule — implement one rule at a time
- By data variation — handle one input type or edge case per story
- By happy vs. unhappy path — success case first, errors later
- By operation — CRUD operations as separate stories
Epics vs Stories
An epic is a large body of work that can be broken down into multiple stories. Epics often represent a feature or initiative that spans multiple sprints. Stories are the granular, sprint-sized pieces that deliver incremental value.
Common pitfalls
- Writing stories that are actually technical tasks. "Update the database schema" is not a user story—it has no user and no visible outcome.
- Making stories too large. If a story can't be completed in one sprint, split it.
- Including solution details. "As a user, I want a dropdown" prescribes UI instead of describing the need.
- Writing without understanding the user. Stories grounded in assumptions rather than research lead to the wrong features.
- Treating the format as a substitute for research. The template helps structure thinking, but it doesn't replace talking to real users.
NZ context
In NZ government and enterprise contexts, user stories bridge the gap between business stakeholders who think in outcomes and technical teams who think in implementation. Agencies like the Department of Internal Affairs and Ministry of Business, Innovation and Employment use story-based backlogs to align multi-vendor delivery teams with policy outcomes.
Local teams often face additional constraints: procurement cycles, ministerial reporting, and integration with legacy Crown systems. Well-written user stories help non-technical stakeholders understand what the team is building and why, without requiring them to read architecture diagrams.
The Service Innovation Lab approach and Digital Service Design Standard both emphasise starting with user needs—user stories are one of the most practical tools for doing that at sprint level.
Career level guidance
Graduate Tester
Learn the user story format and how to read acceptance criteria. Ask questions when stories are unclear before you start testing. Practise writing Given-When-Then scenarios for existing stories.
Junior Tester
Write acceptance criteria for stories during refinement. Identify when a story is missing edge cases or unclear scope. Start contributing to story splitting discussions with testability in mind.
Senior Tester
Facilitate story refinement sessions. Coach the team on INVEST and help rewrite stories that are too technical or too vague. Define test strategies that map back to story acceptance criteria across epics.
Test Lead
Set the team's story quality standards and definition of ready. Review stories before sprint planning to ensure they are testable, valuable, and appropriately sized. Mentor testers on story-writing and acceptance criteria practices.
Industry Reality
- Most teams don't follow INVEST rigorously — stories are often too large, technically phrased, or written by a single person without conversation. In practice, "good enough to start" wins over textbook purity.
- The "As a / I want / So that" format frequently gets dropped in favour of bullet-point descriptions or even Jira summary lines like "Add export to CSV." Senior testers learn to extract the user need regardless of format.
- Acceptance criteria are often written by BAs or product owners after the fact — or not at all. Testers end up writing them retroactively to close ambiguity, which is why the skill of crafting AC is critical even if it's not formally your job.
- Government and large-enterprise teams in NZ sometimes layer user stories on top of formal requirements documents (BRS/FRS), meaning you're testing against two overlapping sources of truth that don't always agree.
- Story splitting is preached but rarely practised well under delivery pressure. Teams ship oversized stories, mark them done-ish, and carry technical and testing debt into the next sprint.
Context guide
How the right level of User Stories effort changes based on team context.
| Context | Priority | Why |
|---|---|---|
| NZ government digital service (e.g. TransitNZ licence renewal, Benefits NZ benefit application) | Essential | Policy is written in outcomes, not screens. User stories translate ministerial intent into sprint-sized pieces that non-technical stakeholders can verify. Without them, delivery teams build what they think policy means, not what citizens actually need. |
| Multi-vendor delivery programme (e.g. Revenue NZ, HealthNZ platform modernisation) | Essential | When four vendors integrate into one Crown system, user stories become the shared contract that each vendor tests against. Ambiguous stories cause integration failures at the seams — precisely where no single vendor owns the defect. |
| NZ fintech or banking product team (e.g. Harbour Bank, Pacific Bank mobile banking feature) | High | RBNZ conduct obligations and the Privacy Act 2020 require traceable rationale for product decisions. Stories with explicit "So that" clauses and written AC produce that trail as a natural by-product of delivery, not as a separate documentation effort. |
| Small NZ SaaS startup with a co-located team (fewer than 10 people) | Medium | Shared context reduces the need for formal story structure, but written acceptance criteria still prevent the "I thought you meant X" conversations in UAT. Keep the format lightweight — a two-line story with three AC lines beats a sticky note with nothing. |
| Regulatory compliance project with fixed scope (e.g. Privacy Act 2020 breach-notification workflow) | Medium | Scope is dictated by legislation, not by user research, so story negotiability is constrained. Still worth using them to surface implementation choices and testability, but pair each story with a traceability link back to the specific section of the Act being satisfied. |
| Internal tooling or infrastructure migration (e.g. TeleNZ network operations console) | Low | Users are internal technical staff who can directly validate against technical specifications. The overhead of full story format adds little; a task list with clear done criteria is often sufficient. Reserve the story format for the handful of workflows that cross team boundaries. |
Trade-offs
What you gain and what you give up when you adopt User Stories.
| Advantage | Disadvantage | Use instead when… |
|---|---|---|
| Stakeholders without technical backgrounds can read, challenge, and prioritise stories — the backlog becomes a shared planning tool rather than a developer artefact. | Stories can mask complexity: a single sentence hides integration dependencies, data migration costs, and security requirements that only surface during development or testing. | The system involves multiple external parties or regulated interfaces (e.g. an NZISM-compliant system integration) and a formal use case or requirement document is needed for contractual or audit purposes. |
| Acceptance criteria written before development start act as a testability forcing function — the team is compelled to agree on "done" before a line of code is written, reducing late-stage defects. | In large organisations (e.g. FamiliesNZ case management, CoverNZ rehabilitation systems) user stories rarely replace the formal documentation that procurement, legal, and assurance reviewers require. Running dual artefacts doubles the maintenance burden. | Scope is fixed by legislation or contract and there is genuinely nothing to negotiate — a detailed requirements specification with explicit traceability gives assurance reviewers the evidence trail they need without the fiction of "negotiability." |
| Story splitting creates a natural rhythm of incremental delivery — teams ship working software more frequently, which reduces risk and keeps stakeholders engaged with real progress rather than Gantt chart projections. | Story granularity decisions are genuinely difficult and time-consuming. Teams frequently get them wrong — either writing stories so large they span three sprints, or splitting so finely that every card feels pointless and coordination overhead dominates delivery. | The team is co-located, the work is purely exploratory (e.g. a spike or proof of concept), and shared understanding already exists — a brief task description or Kanban ticket with a time-box is lighter and equally effective. |
| The format preserves focus on user outcomes rather than technical implementation — "As a KiwiSaver member I want to see my balance" resists feature-creep more than "build a balance-display component" because any proposed scope change must be justified in terms of user value. | Stories without genuine user research behind them produce a false sense of user-centricity. Teams write "As a user I want…" without talking to a single real user, then test against acceptance criteria that reflect internal assumptions rather than actual user behaviour. | The work is infrastructure, platform, or DevOps in nature with no direct end-user interaction — enabler stories or plain technical tasks with explicit outcomes are more honest artefacts than forcing an infrastructure change into "As a developer I want…" phrasing. |
Enterprise reality
How user stories change at 200–300-developer scale across NZ enterprise — more governance, more tooling, more coordination overhead.
- Story authoring becomes a regulated artefact at organisations like Revenue NZ, where stories touching tax calculation or income-data access must align with the Privacy Act 2020 Schedule 1 principles and carry a privacy-impact note before sprint planning — a manual QA check that's increasingly automated via Jira script listeners that flag missing labels.
- At 10+ squad scale, a shared "story template library" replaces individual authoring habits — CloudBooks and ListRight use centralised Confluence macros and Jira issue templates so acceptance criteria formatting, test-type tags (functional, security, performance), and Definition of Ready fields are enforced consistently, not negotiated per team.
- Governance frameworks like NZISM (for government agencies) and PCI DSS (for payment processors such as Harbour Bank) require traceability from story to test to evidence — meaning stories need unique IDs that thread through your test management tool (Zephyr, Xray) and into your CI pipeline so an auditor can pull a compliance report without manual cross-referencing.
- Dependency management dominates at enterprise scale — a single story touching a shared API gateway (common at TeleNZ across consumer, business, and wholesale squads) triggers cross-team impact analysis sessions; many organisations introduce a lightweight "story review board" or use automated dependency-detection tooling to surface upstream blockers before stories enter sprint.
◆ What I would do
Professional judgement — when to adopt User Stories, when to adapt them, and what to watch for.
The bottom line: A user story is only as good as the conversation it forces the team to have before work starts — if your stories are going into sprints without a real Three Amigos discussion and written AC, you are not doing user stories, you are doing sticky notes with extra steps.
Best Practices
- ✓ Write acceptance criteria in Given-When-Then format during refinement, not after development starts — ambiguity caught early costs far less to fix.
- ✓ Challenge the "So that" clause: if it just says "so that I can do the thing," the business value is unclear and the story should be rewritten.
- ✓ Keep testers and developers in the same refinement session — testers surface edge cases, developers flag technical constraints, and the story improves before a line of code is written (the "Three Amigos" approach).
- ✓ Apply INVEST as a checklist at sprint planning, not just at story creation — stories drift over time through scope additions and comments.
- ✓ Use story maps (Jeff Patton's approach) to see user journeys holistically before drilling down to individual stories — this prevents building features that work individually but don't connect.
- ✓ Add a "Definition of Ready" checklist for stories entering the sprint: AC written, dependencies identified, UI mocks available where needed, and security/privacy impacts noted.
- ✓ When a story is blocked or changes mid-sprint, update the AC rather than keeping the original as the source of truth — stale AC misleads testers and creates false pass/fail outcomes.
- ✓ For NZ government projects, map user stories to the relevant Digital Service Design Standard principle (e.g., "Start with user needs") to satisfy assurance reviewers and maintain audit trails.
Common Misconceptions
❌ Myth: User stories replace requirements documentation
Reality: User stories are conversation starters, not replacements for documentation. The conversations, decisions, and acceptance criteria generated around a story are the real artefact. In regulated environments (banking, health, government) you will still need to produce formal requirements or traceability matrices — stories sit alongside these, not instead of them.
❌ Myth: Anyone can write a good user story in two minutes
Reality: The template is simple; writing a genuinely good story is not. Stories written without real user research, without a clear "So that" value, or without testable acceptance criteria cause more confusion than traditional specs. Good stories require understanding the user, the business context, and the technical constraints — that takes time and cross-functional input.
❌ Myth: Once a story is accepted it's done and shouldn't be reopened
Reality: Accepted stories can and do get reopened — when regression is found, when a downstream story reveals a gap, or when the original AC turned out to be wrong. Treating acceptance as permanent creates a culture where bugs are hidden as "new stories" rather than acknowledged as defects. Good teams distinguish between scope changes (new story) and incomplete implementation (reopen).
Senior engineer insight
Teams who use user stories well treat them as a forcing function for shared understanding — not a documentation format. The single most reliable differentiator is whether the team holds a genuine Three Amigos conversation (tester, developer, BA) before work starts; teams that skip that step inevitably discover the ambiguity at the worst possible moment, during UAT or production. The pattern that consistently works: write the acceptance criteria as failing test scenarios first, then let the story evolve from those scenarios rather than the other way around.
The most common mistake: treating user stories as a lightweight substitute for thinking. Teams write the template in thirty seconds, skip the "So that" clause, add no acceptance criteria, and wonder why testing is chaotic. The format is a scaffold — the real work is the conversation it's supposed to trigger.
From the field
A Wellington-based digital agency was delivering a benefits-assessment portal for a Crown entity. The team assumed "As a case worker, I want to view an applicant's full history" was a well-understood story — it had been in the backlog for two sprints and no one had raised concerns. When the testers finally got their hands on it, it emerged that "full history" meant three completely different things to three different case worker roles, and the acceptance criteria said nothing about which role saw what. The sprint delivered a working screen that satisfied none of the actual users. The fix wasn't technical — it was splitting the story into three role-specific stories, each with explicit AC defining visibility rules, and holding a refinement session that included two actual case workers rather than just the product owner. The lesson that applied beyond that team: if your user type in "As a…" is a broad job title rather than a specific role with a specific context, the story is almost certainly hiding multiple distinct needs that will only surface during testing.
Why teams fail here
- Writing stories from the system's perspective rather than the user's — "The API should return a 200 response" is not a user story; it has no human outcome and cannot be validated by a business stakeholder.
- Allowing stories to carry implicit acceptance criteria — when the "done" standard lives in someone's head rather than on the card, testers have no authoritative source of truth and bugs hide behind differing interpretations.
- Skipping story splitting under delivery pressure — a story estimated at 13 points is not sprint-ready; teams that push it through anyway create testing debt that compounds across sprints and makes velocity metrics meaningless.
- Treating the "I" in INVEST as aspirational — stories with hidden dependencies on other stories in the same sprint create cascading blocks; testers can't close a story if the upstream data it depends on hasn't shipped yet.
Key takeaway
A user story done well is not a piece of text on a card — it is a shared, tested agreement about what value the team is committing to deliver, written in language a real user could verify.
How this has changed
The field moved. Here is how User Stories evolved from its origins to current practice.
Kent Beck introduces user stories in XP as a lightweight alternative to use cases. The "As a user, I want... so that..." format provides a placeholder for a conversation, not a complete specification.
Mike Cohn popularises user stories in "User Stories Applied." INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) provide guidance for writing good stories.
Acceptance criteria become a standard user story extension — the conditions that must be true for the story to be "done." Three Amigos sessions formalise the collaborative acceptance criteria conversation.
Story splitting patterns (by workflow, interface, data, rules) help teams break large stories into independently deliverable thin slices. Splitting stories without losing value becomes a valued skill.
AI tools generate user story candidates from requirements, suggest missing acceptance criteria, and identify stories that are too large or ambiguous. The tester's "how will we know this is done?" remains the most important quality gate.
Self-Check
Click each question to reveal the answer.
Q: Your team is testing a new KiwiSaver hardship withdrawal feature on an Revenue NZ self-service portal. During refinement the story reads: "As a KiwiSaver member, I want to apply for a financial hardship withdrawal, so that I can access my funds in an emergency." There are no acceptance criteria and the sprint starts in two days. What do you do, and what specific AC would you propose?
A: Raise a Definition of Ready concern immediately — a story without AC is not sprint-ready. Propose AC covering the key paths: eligibility check (member must have suffered significant financial hardship), document upload, confirmation email within 24 hours, and rejection notification with reason. Also flag edge cases: joint KiwiSaver accounts, members with multiple providers, and accessibility requirements under the Digital Service Design Standard. Push for a mini Three Amigos session with the BA and developer before the sprint begins.
Q: An CoverNZ portal team is under delivery pressure and the Product Owner proposes merging three separate stories — "upload medical certificate," "view claim status," and "download decision letter" — into one story to hit the sprint velocity target. How do you evaluate this, and what is the risk?
A: This violates the Small and Testable principles of INVEST. Combining three distinct user goals inflates the story, makes it harder to test incrementally, and obscures which piece of value is delivered if the sprint runs short. The velocity gain is illusory — the work doesn't shrink just because it's one card. Recommend keeping them separate and, if capacity is the concern, descoping one story rather than merging. A merged story also makes it impossible to ship partial value; if upload works but download doesn't, the whole story is blocked.
Q: What is the key difference between a user story and a use case, and when would you choose one over the other?
A: A user story is a lightweight, conversation-starting placeholder — it captures who, what, and why in one sentence and defers detail to discussion. A use case is a structured document that describes all actor interactions, pre/post conditions, main flow, and alternate flows in formal detail. User stories suit agile teams where requirements evolve through collaboration; use cases suit environments requiring upfront documentation for compliance, multi-vendor contracts, or regulatory audit — common in NZ health, justice, or government procurement where a Business Requirements Specification is still mandated. In practice, some NZ teams use both: stories drive sprint delivery, use cases satisfy the formal assurance gate.
Q: A developer says "We write all our user stories in Jira as one-line summaries like 'Add RealMe login' — the detail is in our heads, so we don't need the full As a / I want / So that format or written AC." What is wrong with this, and how do you respond?
A: The format itself is not the point — the problem is that "in our heads" is not a shared, verifiable source of truth. Without written AC, testers have no objective pass/fail criteria, new team members can't onboard, and the team can't agree on done. The "As a / I want / So that" structure forces the team to name the user and state the value, which surfaces assumptions early. For RealMe login specifically, missing AC risks skipping critical scenarios: users with no RealMe account, expired RealMe credentials, privacy consent step, and what happens when RealMe is unavailable. Suggest a lightweight rule: any story that hits the sprint board must have at least three AC lines — that's the minimum to make it testable.