User story format

Contract

Enforces the three-clause agile story template on every requirement or backlog item you write: As a <specific role>, I want <capability>, so that <benefit>, with acceptance criteria attached as a separate list and one story per need. Apply when turning needs into backlog items; not when estimating effort, planning a roadmap, or writing end-user documentation.

Rules

1. Three clauses, fixed order. Every story is one sentence: As a <role>, I want

<capability>, so that <benefit>. The benefit clause starts with "so that" — not "because", not a bare "to", and never omitted. A story missing any clause is incomplete.

1. The role is specific. Name the sharpest persona the need implies — "a returning shopper",

"an on-call operator", "a first-year student" — never a bare "user" or "customer" when a sharper role exists. The role is a person with a goal, not a team, a company, or the system.

1. Capability says WHAT, never HOW. No solution detail inside the story sentence: no

screens, buttons, dropdowns, tables, endpoints, or vendor names. "I want to receive my receipts by email" — never "I want a Settings-page toggle that writes to the receipts table".

1. The benefit is a reason, not an echo. The "so that" clause states why the capability

matters — the value gained or the pain removed. If it merely restates the want ("...so that I can do it"), dig for the underlying reason and write that instead.

1. Acceptance criteria are a separate list. Each story carries an Acceptance criteria:

block underneath — short, testable statements, one per line. They are never packed into the story sentence itself.

1. One story per need. A compound ask ("reserve a tool and get return reminders") becomes

two stories, each independently deliverable and testable. Split on the "and" whenever the two halves could ship separately.

Worked examples

Requirement prose (the base's default) on top; the conforming story below.

A library's online renewal request:

BEFORE  The system shall allow renewal of borrowed items via the catalog,
        with a renew button on the loans page.

AFTER   As a library member with items on loan, I want to renew my loans
        online, so that I avoid late fees when I cannot visit in person.

        Acceptance criteria:
        - A loan within its renewal limit can be renewed before its due date.
        - The new due date is shown immediately after renewal.
        - An item already reserved by another member cannot be renewed.

A billing feature written as a solution:

BEFORE  Add a PDF export dropdown to the billing page (reads the invoice table).

AFTER   As a freelance designer, I want to download each of my invoices as a
        PDF, so that I can attach clean records to my tax filing.

A compound ask, split into two stories:

BEFORE  As a co-op member, I want to reserve a tool and get reminded to
        return it, so that borrowing runs smoothly.

AFTER   As a co-op member, I want to reserve a tool ahead of pickup,
        so that it is available when I arrive.

        As a co-op member, I want a reminder before my return date,
        so that I do not keep a tool that others are waiting on.

A generic role, sharpened:

BEFORE  As a user, I want delay alerts, so that I know about delays.

AFTER   As a daily rail commuter, I want an alert when my usual line is
        delayed, so that I can leave earlier or reroute before I am stuck.

Edge cases & exceptions

• Developer-facing needs still get a person as the role: "As an on-call operator, I want

..." — the role is whoever feels the benefit, even for internal tooling.

• Several personas want the same capability with different criteria → one story per

persona; if the criteria are identical, name the primary persona rather than "user".

• A stop-doing complaint is still a want: phrase the desired state ("I want a single weekly

digest"), not the grievance.

• Pure technical enablers (upgrade a runtime, rotate a certificate) have no story of their

own; attach them as tasks under the story they unblock, or name the internal role who benefits.

Do / Don't

• Do write role → capability → benefit in one sentence. Don't write "The system shall ..." prose.
• Do start the benefit with "so that". Don't drop the clause or swap in "because".
• Do name a sharp persona. Don't default to "As a user" when the task names someone real.
• Do keep the how out of the story. Don't mention pages, widgets, schemas, or vendors in it.
• Do attach acceptance criteria as their own list. Don't inline them into the sentence.
• Do split compound needs. Don't chain two deliverables with an "and" in one story.

Common mistakes

• Requirement prose: "The system shall ...", "Add a button that ..." — no role, no benefit.
• A benefit that parrots the capability ("...so that I can renew online").
• "As a user" everywhere, even when the task names a nurse, a picker, or a foreman.
• Implementation smuggled into the capability clause (widget names, table names, endpoints).
• Acceptance criteria missing entirely, or welded into the story sentence.
• One mega-story carrying two or three separable needs joined by "and".

Quick checklist

• One sentence: As a <specific role>, I want <capability>, so that <benefit>.
• Benefit clause present, starts with "so that", gives a real reason.
• Role is the sharpest persona the task implies — not a bare "user".
• No implementation detail inside the story sentence.
• Acceptance criteria: list attached under every story.
• Compound needs split — one story per need.