--- name: user-story-format source: https://app.decimal.ai/s/user-story-format@1/SKILL.md source_sha256: 881c91a14346 --- # User story format ## Contract Enforces the three-clause agile story template on every requirement or backlog item you write: `As a , I want , so that `, 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 , I want , so that `. The benefit clause starts with "so that" — not "because", not a bare "to", and never omitted. A story missing any clause is incomplete. 2. **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. 3. **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". 4. **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. 5. **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. 6. **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 , I want , so that `. - 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.