Learn

/

User Story Template

User Story Template

6 patterns

As a, I want, so that. Ron Jeffries' three Cs. Why the so that clause is the part that survives a refactor of the template, and how to write it in plain prose without losing the discipline.

Avoid
Story
NOTIF-12
3 pts
Weekly digest emails
User story
As auser
I wantweekly digest emails
so thatI get weekly digest emails

Prefer
Story
NOTIF-12
3 pts
Active users see what they missed in a weekly digest
User story
As auser who logs in less than once a week
I wanta Monday digest of activity in spaces I follow
so thatI can decide whether to log in without scanning the app for changes
Why avoid

Filling the Connextra fields with 'a user wants weekly emails so they get weekly emails' is process theater. The clauses are present but they answer none of the three questions. The team will rediscover what success looks like in review and probably get it wrong.

Why prefer

The three Connextra clauses force the answers to who, what, and why before the story enters a sprint. The tradeoff space is now visible: the audience is low-frequency users, the value is reducing the cost of staying informed.

Agile Alliance: User Story Template
Avoid
Story
BIL-44
5 pts
Customer downloads invoice PDF
User story
As acustomer
I wantto download my invoice as a PDF

Prefer
Story
BIL-44
5 pts
Customer downloads invoice PDF
User story
As acustomer being audited
I wantto download my invoice as a PDF with the original timestamps
so thatI can submit a tax-authority-acceptable record without asking support
Why avoid

Without 'so that', the team builds 'a PDF download'. Whether the timestamps match the audit, whether 'support escalation rate' goes down, whether this is even the right format, all evaporate. The work ships. The cost stays.

Why prefer

The 'so that' is the part that survives a refactor of the template. It anchors the work to a real cost the customer is paying, which makes it possible to argue scope down or up against the actual goal.

Agile Alliance: User Story Template
Avoid
Story
SCH-77
3 pts
User can see calendar events
User story
As auser
I wantto see my events for the week
so thatI know what is coming up

Prefer
Story
SCH-77
3 pts
Volunteer coordinators see all upcoming shifts at a glance
User story
As avolunteer coordinator running a weekend event
I wantthe week-view to highlight unstaffed shifts in red
so thatI can fill gaps before Friday without sorting through filters
Why avoid

'A user' is a wildcard that lets the team build for whoever shows up loudest in review. The Connextra template is a forcing function for specificity, and 'user' opts out of the function entirely.

Why prefer

Naming the actor as a volunteer coordinator running a weekend event makes the tradeoffs concrete. Should we sort by time or by gap? Should we send a notification? You cannot answer those for 'a user'.

Ron Jeffries: Card, Conversation, Confirmation
Avoid
Story
CHK-44
5 pts
Build new checkout flow
User story
As acustomer
I wanta new checkout flow
so thatcheckout works
Acceptance criteria
Matches the Notion spec
AC are listed in the doc
See the doc for edge cases

Prefer
Story
CHK-44
5 pts
Returning customers check out in fewer than four screens
User story
As areturning customer
I wantto complete checkout without re-entering address or payment
so thatI do not abandon the cart at the third password prompt
Acceptance criteria
Givena returning customer with a saved address and card
Whenthey click Buy on a product page
Thenthey reach an order summary in two clicks
Givena returning customer whose card has expired
Whenthey click Buy
Thenthey are prompted to update payment without losing the cart
Why avoid

AC that point at a Notion doc collapse Confirmation into 'go read the doc'. The doc may be excellent, but the ticket is useless to anyone scanning the board, and the doc rots at a different cadence than the work.

Why prefer

Card: the title and Connextra clauses fit on a card. Conversation: the framing sets up the team to talk through edge cases. Confirmation: the acceptance criteria are observable on the ticket. All three Cs in the ticket itself.

Ron Jeffries: Card, Conversation, Confirmation
Avoid
Story
PROD-12
3 pts
Inventory page filters
Description

Add filters to the inventory page. Filter by status, location, and SKU prefix. Persist the filters in the URL.


Prefer
Story
PROD-12
3 pts
Inventory managers come back to a saved view
Description

Inventory managers run the same filter many times a day. Right now the filter resets on every page load, so they re-apply it for every check. They want filters to persist across visits, ideally in the URL so they can bookmark or share with the warehouse team.

Why avoid

A bulleted feature list is not a story even if it lists every requirement. It tells the team what to build. It does not tell them why, or for whom, or what to drop if the sprint runs hot.

Why prefer

Plain prose is fine. The three Connextra questions are all answered: inventory managers (who), filters that persist across visits (what), so they stop re-applying the same filter all day (why). The template is a forcing function, not a syntactic requirement.

Agile Alliance: User Story Template
Avoid
Story
OPS-21
3 pts
As an unspecified user, I want database secrets to be rotated, so that they are rotated.
User story
As aunspecified user
I wantdatabase secrets to be rotated
so thatthey are rotated

Prefer
Task
OPS-21
3 pts
Rotate the production database secrets
Description

Quarterly rotation, scheduled. Coordinate the cutover with the on-call.

Why avoid

Wrapping plumbing work in a fake 'as a user' clause is process theater. It violates Bill Wake's V (Valuable to a user) and adds noise. The honest move is to call it a Task.

Why prefer

Secret rotation is real work with no user-facing change, so it gets a Task. Trying to force a Connextra clause around it produces tautology. The template is a sanity check for stories, not a costume that every work item has to wear.

Atlassian: Epics, Stories, and Initiatives