To write a user story, begin with the check and finish with the sentence. Name who would notice if the change were wrong and what they would see, settle the open points in conversation, then write “As a [role], I want [capability], so that [benefit].” A story is finished when someone can check it, so the card comes last.
The sentence is the smallest part of a user story
The usual guide to the user story teaches one sentence. Mike Cohn, who advocates the three-part template, traces it to Rachel Davies at Connextra, a UK company, in the early 2000s, and names its parts who, what and why. That sentence is worth learning, and it is a third of the job.
Ron Jeffries set out the other two thirds in 2001. In Card, Conversation, Confirmation he gives a user story three aspects. The card is “a token representing the requirement” and “does not contain all the information that makes up the requirement.” The requirement itself travels “through conversation,” and the confirmation is the acceptance test, in which the customer tells the programmers “how she will confirm that they’ve done what is needed.”
A team that writes in that order can stop at the card, because the card looks finished. Write in reverse and start from the confirmation, the only one of the three that a build can fail. Worked criteria in each format are collected in acceptance criteria examples. What follows is how a story comes to have any.
A story starts with who would notice it going wrong
Take a rough request: “Let patients reschedule their appointments online.” A clinic’s practice manager wrote it, and a developer could start on it today. Nobody could check it, because it names no person and no result.
Before touching the template, put two questions to the request. Who would notice if this shipped wrong? What would they see? Each answer is a check in rough form.
| Who would notice | What they would see if it were wrong | The check it becomes |
|---|---|---|
| The patient | They arrive at the new time and the clinic expects them at the old one | After a move, the patient’s booking page, the confirmation message and the clinic calendar show the same new time |
| The receptionist | The old slot still looks taken, so nobody else can book it | The old slot is open to other patients as soon as the move is confirmed |
| The practice manager | A move made shortly before the appointment leaves a gap nobody can fill | Inside the clinic’s cutoff, the page offers the phone number and no move |
That is three ways to be wrong before the template has been used, and INVEST ends in Testable. In his 2003 article INVEST in Good Stories, and SMART Tasks, Bill Wake says that writing a story card “carries an implicit promise,” which he words as “I understand what I want well enough that I could write a test for it.” Writing the checks first is one plain way to keep that promise.
Wording each check so that a build can fail it is a separate skill, argued in how to write acceptance criteria.
The conversation settles what the checks leave open
The table raised questions the request never answered. How close to the appointment may a patient still move it? May they move to a different practitioner? The practice manager has to answer these. A question nobody asks gets answered anyway, by whoever is writing the code that day.
This is the conversation in Jeffries’ three, and the checks give it an agenda. He writes: “When the conversation about a card gets down to the details of the acceptance test, the customer and programmer settle the final details of what needs to be done.”
Each question ends in one of three ways. A small answer becomes a check: the manager sets the cutoff, and the last row gets a real boundary. A large answer becomes its own story, so moving to another practitioner gets a card of its own and this story stays small enough to build and test in one go. An unknown stays a question with a name beside it.
There is a limit. Wake calls a good story negotiable: “It is not an explicit contract for features; rather, details will be co-created by the customer and programmer during development.” A handful of checks agreed before the build is a starting position. Screen layouts and field lists go further than a story should, and Jeffries says of window sketches and multi-page documents that he has “almost never found this kind of document to be ideal.”
The three-part sentence is written last
Now the template is easy, because every part of it already exists.
| Part of the sentence | Where it comes from | In the clinic story |
|---|---|---|
| As a [role] | The first person in the who-would-notice list | As a patient with a booked appointment |
| I want [capability] | What changes for that person, with no interface in it | I want to move it to another open slot myself |
| so that [benefit] | The reason the request was made | so that I do not have to phone the clinic during opening hours |
The finished story reads:
As a patient with a booked appointment, I want to move it to another open slot myself, so that I do not have to phone the clinic during opening hours.
Beneath it sit the three checks from the first table, with the manager’s cutoff filled in, and a note that changing practitioner is a separate story. Those lines are the story’s acceptance criteria, and they were written before the sentence was.
The benefit clause does real work here. The story exists to spare the patient a phone call, and the cutoff is the one check that sends them back to the phone, so the manager knows which rule to keep as narrow as the clinic can bear.
Cohn leaves room to bend the template. He does not treat the so-that clause as mandatory, “because sometimes it just doesn’t add any value.” A copyable version, with the checks laid out beneath the sentence, is the user story template.
Weak stories fail when someone tries to check them
The usual lists of user story mistakes read as style rules. Each mistake is easier to see as a check that cannot be written.
| The failure | What it looks like | What trying to check it shows |
|---|---|---|
| The role is “user” | As a user, I want to reschedule | Nobody in particular would notice it going wrong, so nobody can say what wrong looks like |
| The capability is a solution | I want a Reschedule button on the booking page | The only check available is that the button exists |
| The benefit repeats the capability | so that I can reschedule | There is nothing to weigh the cutoff or any other trade against |
| The story is a task | As a developer, I want the booking table indexed | No one outside the team could see it pass or fail, so it belongs inside a story |
| The story is an epic | As a patient, I want to manage my appointments | The who-would-notice list keeps growing, and each cluster of rows is a story of its own |
| The card stands alone | A sentence with nothing beneath it | The tester invents the checks during testing, and the first disagreement happens at the demo |
The last row is the one a template cannot fix. A well-formed sentence with no confirmation looks complete in a backlog, and a story can reach a sprint that way with its hardest questions unasked.
Writing backwards also names who should look at the result. The receptionist who would notice a stuck slot is the right person to try the built page. With the Notarus widget on that page, the widget captures what they are looking at and gives them a pen to circle the slot, and the console logs, network activity, page URL, viewport and browser travel with the report as captured evidence. What arrives depends on capture settings and the browser, and whether the slot should have been free is still decided by the story.
A story written this way has one sentence on the card and the rest underneath, and the rest is what gets checked.
