Template
Bug report template
A copyable bug report template with the fields that decide whether a report can be acted on: environment, steps, expected against actual, evidence.
A user story template that says when the story is done
A user story template is a card with a fixed set of fields: the story sentence (As a [role], I want [capability], so that [benefit]), the context behind it, acceptance criteria, what is out of scope, dependencies, a size, and how the result will be checked. The sentence says who wants the change and why. Every field under it exists so a team can build the story and agree when it is finished.
- Template
- 8 fields, explained
- Updated
A user story template often stops at one sentence. As a, I want, so that names a person, a change and a reason, and it leaves out everything a developer and a tester ask next: which cases count, what was left out on purpose, what has to exist first, and who decides the work is done.
In the template
- Story
- Context
- Acceptance criteria
- Out of scope
- Dependencies
- Size
- How it will be checked
User story template, ready to copy
Copy it as it is. There is no email step, and nothing on this page is behind one.
# User story: [ID] [short title] ## Story As a [role], I want [capability], so that [benefit]. ## Context Why this is coming up now, and where the request came from: Link to the design, the research or the tickets behind it: ## Acceptance criteria Rules, one condition per line, each true or false of the build: 1. 2. 3. Scenario, for an outcome that depends on what came before: Given [starting state] When [one action] Then [what the user can observe] ## Out of scope What this story will not do, and where that work lives instead: ## Dependencies What has to exist first, and who owns it: ## Size Estimate: What the estimate assumes: ## How it will be checked Environment: Checked by: Accepted by (one person):
# User story: PROD-431 Email me when a sold-out product is back ## Story As a shopper looking at a sold-out product, I want an email when it is back in stock, so that I can buy it without checking the page every day. ## Context Why this is coming up now, and where the request came from: a sold-out product page offers no next step, and support answers the same question by hand. Those tickets are collected under SUP-88. Link to the design, the research or the tickets behind it: product page design, version 6, the frame named Sold out. ## Acceptance criteria Rules, one condition per line, each true or false of the build: 1. The sign-up control appears on a product page only while that product is sold out. 2. A signed-in shopper signs up in one action, with the email address on the account. A guest is asked for an address. 3. Signing up twice for the same product with the same address sends one email. 4. One email is sent when the product's stock rises above zero. It names the product and links to its page. 5. The sign-up ends when that email is sent, and the address is used for nothing else. Scenario, for an outcome that depends on what came before: Given a shopper who signed up for SKU-2207 while it was sold out When the stock of SKU-2207 is changed from 0 to 5 Then one email naming SKU-2207 reaches their address, and the product page shows Add to basket in place of the sign-up control ## Out of scope What this story will not do, and where that work lives instead: alerts per size or colour, which are PROD-438. Text messages and push notifications, which are not planned. Adding the address to the newsletter list, which rule 5 rules out. ## Dependencies What has to exist first, and who owns it: the restock event from the inventory service, owned by the platform team and already live. The email template, owned by design and due before the sprint starts. ## Size Estimate: 5 points What the estimate assumes: the restock event fires on every stock change. If it has to be added, the story is estimated again. ## How it will be checked Environment: staging, on the build that carries the story, with a test product whose stock can be set by hand. Checked by: QA, against the five rules and the scenario. The email is read in the staging mailbox, never inferred from a log line. Accepted by (one person): the storefront product owner.
The card below keeps the sentence and adds those answers as fields, short enough to paste into the description box of a tracker. The filled-in version is the same card written for one story on a web shop, so each field shows how specific it has to be before somebody else can act on it.
What each field is for
Scroll the table sideways for the examples.
| Field | Why it earns its place | Example |
|---|---|---|
| ID and title | The tracker's reference and a few words naming the change. The ID is what a test case, a commit and a bug report cite later, so it has to stay the same when the wording of the story is edited. | PROD-431 Email me when a sold-out product is back |
| Story | One sentence in three parts: who wants the change, what they will be able to do, and what that gets them. The role and the benefit are the two slots that get filled lazily. A role as broad as user fits every story ever written, and an outcome that restates the capability gives the team nothing to test a design against. | As a shopper looking at a sold-out product, I want an email when it is back in stock, so that I can buy it without checking the page every day. |
| Context | Why the request is coming up now and where it came from, with a link to the design, the research or the tickets behind it. Two lines here spare the start of the refinement conversation, which otherwise goes on reconstructing what the author already knew. | A sold-out product page offers no next step, and support answers the same question by hand. Tickets collected under SUP-88. |
| Acceptance criteria | The conditions the finished story is judged against, in two slots. A numbered rule holds a condition that is true or false whatever came before. The Given, When, Then lines hold an outcome that depends on a starting state. Delete whichever slot the story does not need, and keep the numbers, because they are what a test case or a bug report points at. | 3. Signing up twice for the same product with the same address sends one email. |
| Out of scope | What a reader might reasonably assume is included and is not, with the story that will carry it. This is the field that keeps a story small without losing track of the work that was cut. | Alerts per size or colour, which are PROD-438. Text messages and push notifications, which are not planned. |
| Dependencies | Anything that has to exist before the work can start or finish, and who owns it: a design, an API, a decision, another story. Writing None is an answer. An empty field is not, because nobody can tell whether the question was asked. | The restock event from the inventory service, owned by the platform team. The email template, owned by design. |
| Size optional | The team's estimate in whatever unit it uses, and the assumption the number rests on. The assumption is the half worth writing down, because it says when the estimate stops being valid. | 5 points, assuming the restock event fires on every stock change. If it has to be added, the story is estimated again. |
| How it will be checked | The environment the story will be judged on, who runs the checks, and the one person who accepts the result. Checks that apply to every story belong in the team's definition of done. This field holds only what is particular to this story. | Staging, with a test product whose stock can be set by hand. QA runs the five rules and the scenario; the storefront product owner accepts. |
A user story nobody can check, and the same story somebody can
Not this
As a user, I want to be notified about stock so that I have a better experience. Acceptance criteria: notifications work.
This instead
As a shopper looking at a sold-out product, I want an email when it is back in stock, so that I can buy it without checking the page every day. Rules: the sign-up control appears only while the product is sold out; signing up twice with the same address sends one email; one email is sent when stock rises above zero, and the sign-up ends with it. Out of scope: text messages, and alerts per size or colour (PROD-438). Checked on staging. Accepted by the storefront product owner.
Both describe the same request. The first passes for a story because it has the three parts, and each part is empty: user fits anyone, notified about stock could be one of several features, and a better experience is the reason given for everything. Notifications work cannot fail, so it cannot be checked either. The second took a few more minutes to write. What those minutes bought is that a developer can start, a tester knows three things to try, and the question about sizes was asked and answered before the sprint.
Two slots for acceptance criteria, because a story usually holds both kinds of rule
A rule that holds whatever came before reads best as one line: signing up twice sends one email. A rule whose outcome depends on an earlier state needs that state written down, and Given, When, Then is the shortest form that does it. Many stories carry several of the first kind and one or two of the second, so the card offers both and expects one slot to be trimmed or deleted. The rules are numbered for a practical reason. A test case that covers rule 3 and a bug report saying rule 4 failed on staging both point at one line, and a rule that gets reworded keeps its number, so everything pointing at it still lands.
Out of scope is how a user story stays small
A story grows during refinement, one reasonable question at a time. Should it cover every size and colour? Should it send a text message as well? Each answer becomes either a new rule on this card or a line under out of scope, and the second choice is what keeps the story inside one sprint. The line is worth more when it says where the excluded work went. Alerts per size or colour, which are PROD-438, tells a reader the gap is known and has an owner. A bare exclusion with no destination gets forgotten, and the first customer to ask for it finds that nobody remembers deciding.
How it will be checked names a place and a person
Criteria say what will be judged. This field says where and by whom, and both go wrong when they are left to habit. A story checked on a developer's machine was checked against data and settings no customer has. A story accepted by the team was accepted by nobody in particular, so a disagreement at the end of the sprint has no one to settle it. One environment and one name make done a decision somebody took, on a build somebody can point to. When a check fails, the bug report that follows should cite the story's ID and the number of the rule that failed, which is the reason the card carries both.
Which INVEST question each field answers
INVEST is the six-letter check Bill Wake published in 2003 for judging a story: Independent, Negotiable, Valuable, Estimable, Small and Testable. A filled-in card answers most of the letters without a separate review. Dependencies shows how independent the story is, since every line there is something that has to land first. The so that clause carries the value. Size is the estimate, and a team that cannot fill it in has learned the story is not yet estimable. Out of scope is the usual way a story becomes small. Acceptance criteria make it testable. Negotiable has no field of its own, and it is the reason the card is this short: the details stay open into the build, and a card that takes a minute to reread is one a team will still edit.
Common questions
What should a user story template include?
A user story template should include an ID and title, the story sentence, the context behind the request, acceptance criteria, what is out of scope, dependencies, a size, and how the result will be checked. The sentence and the criteria are the two a story cannot do without. The others answer the questions that otherwise surface in the middle of a sprint.
What are the three parts of the user story sentence?
The three parts are a role, a capability and a benefit: As a [role], I want [capability], so that [benefit]. Fill the role with a specific kind of person, such as a shopper looking at a sold-out product. Fill the capability with something that person can do once the work ships, and the benefit with a result that matters to them outside the software.
Who fills in a user story template?
The product owner usually drafts the sentence, the context and the out of scope line, since those come from knowing the user. Developers and testers add the dependencies, the size and most of the edge cases in the criteria during refinement. Accepted by is filled in last and holds one person, normally the product owner.
Does every user story need a Given/When/Then scenario?
Only a story whose outcome depends on an earlier state needs one, such as a sign-up that already exists or a link that has expired. A condition that holds whatever came before is clearer as a single numbered rule, and a card holding rules alone is complete. Delete the scenario slot when nothing in the story calls for it.
Is a user story template the same as a definition of ready?
The two do different jobs. A template is the set of fields one story is written in, and a definition of ready is a team's checklist for deciding whether any story may enter a sprint. They meet at one point: a card with every field filled in has usually answered most of what a readiness checklist asks.
How long should a filled-in user story be?
Short enough to reread in the minute before a planning conversation. A card that needs a long list of rules and several scenarios is usually two stories sharing one title, and the out of scope field is where the second story gets named and given an ID of its own.
Where does a user story template go in an issue tracker?
Put the ID and title in the tracker's own title field and paste everything under it into the description. Where the tracker already has a field for the estimate or for linked issues, fill that field and delete the matching line from the card, so the same fact is not kept in two places.
Terms used on this page
Why the work behind it is hard
More templates
-
Template
Test plan template
A copyable test plan template covering scope, approach, entry and exit criteria, environments, roles and risks. The short version teams actually keep updated.
Template
Test case template
A copyable test case template with the fields that make a run repeatable: preconditions, exact test data, per-step expected results, and a recorded outcome.
Or skip the template and capture the fields automatically.
Environment, console and network attach themselves, on the free plan.