The story is the fundamental unit of work on the project board. It describes a small, deliverable piece of value: what the team is building, why it matters, and how to verify it’s done. If your stories are well-written, everything downstream (estimation, standups, code review, QA) gets easier. If they’re vague, every step of the process will fight you.
For the philosophy behind how to scope stories, see From Problem to Feature: Scoping Work. This page focuses on the practical template.
When you need this#
- Engineers start working on a ticket and immediately need a 20-minute conversation to understand what’s being asked.
- Acceptance criteria are missing or vague, leading to “is this done?” debates during review.
- Tickets describe implementation tasks (“refactor the auth module”) instead of user-facing value (“users can switch accounts”).
- Work gets marked as “done” but loose ends keep surfacing because nobody captured the full definition of done.
What each section is for#
Background - A couple of sentences of context. What does the reader need to know to understand this request? If the ticket uses domain-specific terms, define them here. Don’t assume the person picking up the ticket was in the meeting where this was discussed.
Desired Behavior - What should the user experience look like when this is done? Describe it from the user’s perspective: “When I go to X, I see Y.” Words are more important than screenshots here. Screenshots go stale as the product changes; a clear written description stays accurate. If a screenshot truly helps, include it as a supplement, not a replacement.
Business Case / Why? / ROI - Why is this worth doing right now instead of something else? This helps the team prioritize and challenge scope. If you’re not sure why this is important, it’s better to remove this section than to exaggerate. An honest “this is low priority but easy to knock out” is more useful than a manufactured justification.
Acceptance Criteria - The checklist for “done.” Each item should be verifiable by someone who wasn’t involved in the implementation. Write them as checkboxes so they can be ticked off during QA.
This list should include non-engineering tasks too: notifying a customer, updating documentation, flipping a feature flag. If it needs to happen before the ticket can be closed, it belongs here. (See Your Project Board is a Mirror for more on the definition of done.)
Developer Notes - Optional context from the team to help whoever picks up the ticket. Things like “there’s a similar implementation in the billing service” or “the design team prefers we use the existing component library.” This section is a suggestion, not a requirement. After the story is delivered, delete it. Whether the engineer followed the advice or not is irrelevant once the work is done.
The template#
## Background
<!--
Explain any background or assumed knowledge to understand this story. A couple
sentences usually. This is also a good section to clarify the usage of terms
that others may not know but will be used to describe this request.
-->
## Desired Behavior
<!--
Explain what you would like to see. When I go to X, I want to see A, B, and
not C.
Words are more important here than a screenshot. Screenshots can often lead to
more questions than they are worth because they are too broad (more context than
is needed) or outdated from the site. This means that in a few weeks time, they
no longer make sense as the app has changed.
-->
## Business Case / Why? / ROI
<!--
Why are we doing this over another task?
If unsure, it is better to remove this section than exaggerate a request's
importance. This will help the team challenge if this story is more or less
important to prioritize against others being considered.
-->
## Acceptance Criteria
<!--
Call out what you expect to check when it comes time to QA this feature.
This list should also include things non-development related. Often this can be
notifying the requesting customer of the fix or updating documentation.
If something is missing in QA, it will often result then in a new feature
request. Using a check-list here will make sure things have been verified versus
getting missed when it's a bullet-list.
-->
- [ ] When adding A, B, and C. The admin can see all of these.
- [ ] When adding A, B, and C. The viewer can only see C as it has been approved.
- [ ] Notify {customer} that the fix was shipped.
- [ ] Update Wiki relating to this feature.
- [ ] Update documentation
## Developer Notes
<!--
To be filled in by developers to help accelerate or clarify the above.
Things like where to find code to copy or start with, or translation of terms
between the above.
-->