User Stories

Sixteen stories as teams write them — what is wrong with each, and the rewrite

Nobody needs another explanation of “As a…, I want…, so that…”. What helps is seeing the stories that real backlogs are full of next to the version that works. Here are sixteen, each with what is wrong and a rewrite. Most backlogs contain several of them, and some contain all sixteen. Later sections cite them by number.

Card, conversation, confirmation — what a story actually is

Stories came out of Extreme ProgrammingExtreme Programmingthe engineering-first agile methodAn agile methodology from the late 1990s built around engineering practices: test-first development, pair programming, continuous integration, refactoring and small, frequent releases. Much of what teams now call technical agility comes from it, and a team that adopts Scrum’s events without these practices usually watches its sprints slow down.All terms, the method Kent Beck and his colleagues worked out in the late 1990s, largely on a payroll project at Chrysler. A need was written on an index card in a sentence or two, and the detail was settled by talking to a customer who sat with the team. The card was small on purpose: it could not hold a specification, so nobody could pretend it was one.

On 30 August 2001 Ron Jeffries named the three parts. The Card holds “just enough text to identify the requirement, and to remind everyone what the story is”. The Conversation is where the requirement actually passes from the customer to the programmers, over time — when the story is estimated and again when it is planned. The Confirmation is the acceptance test: how the customer will know the team has done what was needed. All three are required. A card with no conversation is a badly written specification; a conversation with no confirmation is a disagreement waiting for the review.

The familiar template — “As a [role], I want [capability], so that [benefit]” — was not part of the idea. It was a house style at Connextra, a London company, shared with the XP community in 2001, and Mike Cohn’s book of 2004 made it the default. It is a good default. It is also optional, and three alternatives are worth knowing.

Detail arrives just in time

A story is deliberately under-specified when it is written, and it gains detail as it rises towards the top of the backlog. Items for the next sprint or two are small, have their acceptance criteria and have been talked through. Items for the next few months are features with a rough size. Everything further down is an epicepica large backlog itemA large piece of work that is split into features or stories before anyone builds it, best written as a bet with a hypothesis and a condition that closes it. Its size depends on whose vocabulary is in use — anything above a story in Jira, a portfolio investment with a business case in SAFe — so check before comparing two epics.Full article →All terms in a single line. Roman Pichler’s name for a backlog in this shape is DEEP: detailed appropriately, estimated, emergent and prioritised.

The shape is an economic decision rather than a style. Detail written for the bottom of the list is written for a plan that will change before anyone builds it, and it has to be rewritten or quietly ignored. Detail missing at the top means the sprint starts with questions nobody can answer. Some teams protect the top with a Definition of Ready — a checklist a story must pass before it may enter a sprint. Used as a reminder it helps. Used as a gate, as Mike Cohn has warned, it turns a conversation back into a hand-off and the team back into a stage of a waterfall.

Acceptance criteria — the third C

The third C is the one most often dropped (row 9). Acceptance criteria are not bureaucracy; they are the answer to “how will we know?”, agreed before the work starts rather than argued about at the review. They are also the cheapest bug prevention there is: most of what a tester finds in the first hour is a case nobody discussed.

Two formats cover almost everything. A checklist is a plain list of conditions that must hold: fast to write, easy to read, and the right default for simple stories. Given/When/Then states a starting state, an action and an expected result. Dan North and Chris Matts worked it out from late 2004, to give analysts, testers and developers one vocabulary, and North published it in March 2006. It forces you to name the precondition, and it turns directly into an automated test.

Three rules keep them useful. Keep them few: three to seven per story is normal, and fifteen means the story is really two or three (row 11). Make them about behaviour, not the screen: a criterion that names a button’s colour fails the day the design changes and still tells nobody what the button should do (row 12). And keep them measurable: “fast” is not a criterion, “95% under 300 ms” is (row 10).

Example mapping — the conversation made visible

The most useful technique for writing criteria is also the one that most directly restores the conversation (row 16). Matt Wynne, who leads the Cucumber project, described it on 8 December 2015. Three or four people — someone from product, development and testing — take one story and four colours of card. The story goes on a yellow card. Each rule it must follow goes on a blue card. Under each rule go green cards with concrete examples. Any question nobody in the room can answer goes on a red card, to be taken away.

The table that results is the diagnosis. A well-understood, well-sized story maps in about 25 minutes, by Wynne’s estimate. A table covered in red cards means the story is not ready: there is more to learn before anyone should build it. A table covered in blue cards means the story is too big, and each rule is a candidate for its own story (row 11). A rule with a long column of green examples is probably several rules. And the blue and green cards, once the questions are answered, are the acceptance criteria — written by the people who will have to meet them.

Slicing — vertically, and nine ways to do it

This is the single skill that decides whether stories help at all. A vertical slice cuts through every layer — interface, logic, storage — and produces something a user can do. A horizontal slice cuts by technical layer and produces nothing anyone can use until the last layer lands (row 5).

Horizontal slicing is tempting because it matches how teams are often organised and because it feels efficient: the database specialist does the database part, once, properly. It fails for a reason that has nothing to do with efficiency. Nothing is releasable until every layer is finished, so all the feedback arrives at the end, no estimate can be checked until then, and a slip in the last layer wastes all the layers below it.

Nine patterns for splitting a story

On 28 October 2009 Richard Lawrence published nine patterns for splitting stories, and they are still the most complete set. Try them roughly in this order; the first one that produces two stories each worth having is usually the right one.

When several patterns work, Lawrence’s later guide offers two tie-breakers. Prefer the split that lets you deprioritise or throw away one of the halves, because that is the split that reveals what the work was not worth. And prefer the split that gives stories of roughly equal, small size, because that is what makes counting them a forecast.

Story mapping — keeping the journey whole

A flat backlog of well-sliced stories has one structural flaw: it loses the shape of the user’s journey. Read fifty ordered cards and you cannot tell whether the top twenty add up to something a person can complete. Jeff Patton’s story map, which he described on 8 October 2008 and later in a book, fixes that by laying stories out in two dimensions instead of one.

Across the top runs the backbone: the things a user does, left to right, in the order they do them — browse, choose, pay, track. The backbone is not prioritised; it simply is. Beneath each step hangs a column of stories, ordered top to bottom by how necessary they are. The map is then sliced horizontally. The top row across every column is the thinnest version of the journey that works end to end — the walking skeleton, a term Patton borrows from Alistair Cockburn — and each row below it is a later release that makes the same journey better.

The value is in what the shape makes obvious. A gap in the backbone is a step nobody thought about. A column with fifteen cards next to columns with two is where the team has over-invested. And a first release chosen by taking the top row is guaranteed to be usable, whereas a first release made of the top twenty items of a flat list usually is not. Patton’s own image for the risk the map removes: building a car feature by feature, you can end up releasing one without brakes.

INVEST, spikes and what points are for

On 17 August 2003 Bill Wake gave the checklist that is still quoted: a good story is Independent, Negotiable, Valuable, Estimable, Small and Testable. His own wording is more useful than the acronym, so here it is beside the symptom of each letter failing.

INVEST is a smell test, not a gate. A story that fails one letter deserves a second look, not automatic rejection: dependent stories exist, and sometimes the honest answer is to build them in order. The letter to take seriously every time is Testable. Wake put it as a promise the card makes — “I understand what I want well enough that I could write a test for it” — and if nobody can say what would prove a story done, no amount of rewriting the other five will save it. Note also that Wake’s “small” is a few person-weeks; teams now aim much smaller, a few days, because a story that takes the whole sprint has nothing left to absorb a surprise.

When a story is not estimable: the spike

Sometimes a team cannot size a story because the unknown is technical: will this library handle our volume, can the provider’s API do partial refunds at all. The answer is a spike — a separate, time-boxed investigation whose deliverable is knowledge, not working software. Two rules keep spikes honest (row 13). The question and the time box are fixed in advance, and the box is not extended: if two days were not enough, that is itself the finding. And a spike ends in a decision written down somewhere, or the same question is investigated again next quarter by whoever inherits the code.

Points, and what they are not for

Story pointsstory pointsrelative size, not hoursA unit for estimating the relative size of backlog items — an 8 is roughly twice a 5 — deliberately not tied to hours. They are useful for one team’s planning and nothing else: turned into a target or compared across teams, they inflate instead of measuring.Full article →All terms are a relative size, not a duration: this story is about twice that one. They began, by Ron Jeffries’ account, as “ideal days” — a pair’s uninterrupted day — and were renamed points when people kept confusing ideal days with calendar days. VelocityVelocityhow much fits in a sprintHow much a team actually completes in a sprint, averaged over several. It is a planning aid for that one team and nothing else — comparing the velocity of two teams, or setting it as a target, reliably produces inflated estimates rather than more work.Full article →All terms, points finished per sprint, is then a forecasting input for the team that produced it and for nothing else; it is not comparable between teams and it is not productivity, because any team measured on it can double it in two sprints without changing what it delivers. The Estimation page covers the units and their arithmetic.

Five episodes, and what each one changed

The format has a short, well-documented history, and most of what goes wrong with stories today was noticed by the people who shaped it.

C3 is the episode advocates tell least often, and the most instructive. The Chrysler Comprehensive Compensation project began in 1993 and had not paid anyone when Kent Beck arrived in 1996. Under the practices that became Extreme Programming — stories on cards, a customer in the room, short releases — it went live in 1997 and paid about 10,000 monthly-salaried staff. It was meant to pay 87,000. New development stopped in 1999, and DaimlerChrysler cancelled the project in February 2000. The detail worth keeping is about the conversation: the customer representative, the person the stories depended on, left burnt out and was not replaced. Stories put the requirement in a person’s head rather than in a document. That is their strength, and it means the method needs that person, with time, for as long as the work lasts.

Where it degrades

Stories rarely fail because the sentence was badly formed. They fail when the format survives and the mechanism behind it — the conversation, the confirmation, the thin slice — quietly stops. Almost every such failure is one of these:

• The template applied to technical tasks, so “As a developer, I want a migration” fools nobody and hides the user effect (row 2).
• The “so that” dropped, which removes the only reason a story is negotiable (row 1).
• Cards written in full detail by one person, so the conversation never happens (row 16).
• Horizontal slices — API, UI, database — called stories, so nothing ships until the sprint’s last day, or the next sprint’s (row 5).
• No acceptance criteria, so “done” is negotiated at the review under time pressure (row 9).
• Given/When/Then written as scripts of clicks, which break with every redesign and say nothing about behaviour (row 12).
• A Definition of Ready used as a gate, which turns the conversation back into a hand-off.
• The whole backlog detailed up front, so most of the detail is rewritten or ignored before anyone builds it.
• Story points treated as a productivity target, which inflates estimates rather than output.
• Bugs and quality constraints dressed as stories, which makes the backlog look like progress (rows 14–15).

The honest limit is that a story can only carry a need someone has actually understood. The format makes it easy to write down a guess in the voice of a user — “As a customer, I want…” — and the guess then looks like evidence. Nothing in the template checks whether any customer wants it. That check lives elsewhere, in discovery and in what users do after a release; a backlog of perfectly formed stories can describe, slice and confirm a product nobody needed.

The practical check takes fifteen minutes. Open the current sprint and read the titles: can each one ship on its own (row 5)? Count the stories without a reason (row 1) and without acceptance criteria (row 9). Find the three oldest items at the top of the backlog and ask who last talked about each one with somebody from product. And look at the bottom: if items there have detailed acceptance criteria, the team is writing detail for a plan that will change.

When to use it

Related pages

• ManagementEpics, Features, TasksEpics, features and tasks are the levels of a work hierarchy, from a bet a leader makes for a quarter down to a step an engineer takes today. No standard defines them: the Scrum Guide uses none of the three words, and Jira, Azure DevOps and SAFe each put the epic at a different size. The page opens with every level on one screen and one epic taken down to tasks, then covers where the words come from, what each level is for, writing an epic as a bet with an exit, features, enablers and tasks, why rolled-up estimates mislead, five episodes from the hierarchy’s history, and where it degrades.
• ManagementWork Breakdown StructureA work breakdown structure (WBS) is a hierarchical breakdown of everything a project will deliver — and, by definition, nothing it will not. It is a scope boundary drawn as a tree: if a piece of work is not somewhere in it, it is not in the project, and adding it is a change rather than an edit. The page opens with a finished WBS for an IT project — eight branches, thirty-one work packages, coded and adding up to 100% — then covers the rules that make a tree a WBS, the dictionary where scope actually lives, codes and control accounts, how deep to decompose, the WBS beside an agile backlog, three documented cases, and where it degrades.
• ManagementEstimation MethodsEstimation methods in IT are the units a team uses to predict how much work something will take: story points, man-days, hours or T-shirt sizes. They are not interchangeable. Each one moves the step that turns effort into a date to a different place and a different person, and each fails in its own recognisable way. The page opens with all four side by side and a table of which one fits which decision, then covers why an honest estimate is a range rather than a number, each unit in depth, six documented estimates that went wrong, and where estimating turns into theatre.