User Story Template: INVEST in Plain English

The template has three slots and they are not equal citizens. "As a" and "I want" describe a request, and a request cannot be false — only unfulfilled. "So that" makes a claim about the world after release, which makes it the only part of a story that can turn out wrong, and the only part anyone can check. It is also the part teams delete first. Here's what each slot asserts, what belongs in acceptance criteria instead, and when the template is the wrong container.

The story shipped. It demoed well — someone clicked the new control on a call, three people said "nice," and it moved to Done. Six weeks later a director asked the ordinary question: did that help?

Nobody could answer, and not because measurement was hard. The story had never said what "help" would look like, so there was nothing to check. It had been delivered; it had never been evaluated, and never could have been. That gap is structural, and it lives in the template.

Only one slot can be wrong

Read the first two clauses as propositions and ask what would make them false. "As a fraud analyst" isn't a claim; it's an address. "I want my filter set to persist between sessions" is a preference, and a preference is never wrong — you can fail to satisfy it, but no observation can contradict it.

The third clause is different in kind. "So that the morning review queue is assembled in one action instead of eleven" is a proposition about a state of the world that does not yet exist, and it can be false: the queue still takes eleven actions, or it takes one and nobody's day improved.

Requirements engineering has a name for the property that clause supplies: verifiability — the existence of a finite process by which conformance can be determined (ISO/IEC/IEEE 29148:2018). Drop the "so that" and the story keeps its who and its what and loses all verifiable content. What's left is a work order — which can't be right or wrong, only done or not done.

Run this test this week. For your last ten shipped stories, write the past-tense sentence that would be true if each worked, plus the observation that would show it false. The count you can't complete is your real number.

One fork, walked

A labeled illustrative composite, drawn from patterns common in payments risk and manual-review operations; the counts are illustrative, not measured.

A payments company ran a manual fraud-review console. Nine analysts, each starting the day by assembling a queue by hand: date range, risk-score band, three merchant categories, a geography, a disposition status. Roughly eleven selections before the first case appeared. A story went into the backlog to fix it.

How it was written:

REV-118. As a user, I want a "Save this search" button on the filter panel, so that I can save my searches.

Nothing in that sentence can be wrong. The role is user — all nine analysts, both team leads, the compliance people who open the console quarterly, and the engineer testing it. The want names a widget in a location. And the outcome clause is circular: so that I can save my searches restates the want. A circular "so that" is worse than a missing one, because a missing clause is visibly missing.

How it was rewritten, after someone asked what would be observably different a week after release:

REV-118. As a fraud analyst assembling the morning review queue, I want my working filter set applied in a single action at the start of a shift, so that every analyst opens the same defined queue instead of rebuilding it from memory — and no risk band is silently excluded because one person's recipe drifted.

That version forced a question the first couldn't: are the nine analysts rebuilding the same queue, or nine different ones? The word "same" made the claim checkable, and nobody knew the answer.

The discovery move was a query, not a workshop. The console already logged every filter application. Thirty days of logs, grouped by analyst and distinct combination, took an afternoon: thirty-one distinct combinations across nine analysts, where the team believed there were four. Three analysts had recipes excluding card-not-present disputes under $50 — a personal tweak during a busy week two quarters earlier that nobody undid.

So the problem was never eleven clicks. Queue coverage varied by analyst and nobody could see it — and a per-user save button would have made the drift permanent, giving nine improvised recipes a name and a longer life. The team built something else: four shared, named queue definitions owned by the risk lead, versioned, with a nightly assertion that they cover every open case in the review window.

The badly written story would have shipped in four days, passed every criterion attached to it, and demoed well. The rewrite took eleven, and six weeks on the claim was checkable: distinct shift-queue combinations went from thirty-one to four, and the coverage assertion fired twice in the first month, both times on a real gap. The first version could only be delivered. The second could be wrong, which is why anyone learned anything.

If a story is already written and already stuck, the artifact isn't the problem — INVEST Criteria for Better User Stories runs the six letters as a chain to find which one broke. This piece is about the sentence beforehand.

Run this test this week. Cross out the "so that" on your next three stories. If the team could still build them unchanged, the clause was decoration — rewrite it as a state of the world someone could check six weeks after release.

The role slot, and the substitution test

"As a user" is the most common thing written in the first slot, and it is not a role. It's a placeholder that survives review because it's true of everyone — and a role covering everyone constrains nothing. Hence the substitution test: replace the role with two other plausible roles and see whether any criterion changes.

On REV-118: as a fraud analyst, the queue must be complete and consistent, because a missed case is a loss event. As a risk team lead, the capability that matters is defining and auditing queues, not consuming them. As an external auditor, definitions must be versioned so you can prove what an analyst was shown on a given day. Three roles, three different builds. Run it on "as a user" and nothing changes, because nothing was specified.

If you keep writing "as a user" because the honest role is whoever happens to be doing this, the situation matters more than the person. That's what job stories exist for — when [situation], I want to [motivation] — where the trigger replaces the persona.

Run this test this week. Substitute the role on five stories in your current sprint and count how many acceptance criteria change. Zero means your criteria were written for an average user who does not exist.

The want slot, and the three-implementations test

The second failure is quieter and costs more: the want slot names a control instead of a capability. "I want a Save this search button on the filter panel" names a widget, a location, and an interaction model — three design decisions made by the ticket's author, in a sentence everyone downstream treats as a requirement. It's the same error as writing a system requirement where a business requirement belongs: a solution smuggled upstream, inheriting a requirement's authority without being reviewed as a design. Nobody objects, because concreteness reads as rigor.

The test is fast. Can three genuinely different implementations satisfy this sentence? "My working filter set applied in a single action at the start of a shift" admits a saved-search button, a shared queue definition, a bookmarked URL, a role-assigned default view, or an automatic session restore — five options, and the team chose on evidence. "A Save this search button on the filter panel" admits exactly one, and if exactly one fits your sentence, you wrote a design, labeled it a requirement, and spent the team's best chance at a cheaper answer.

Run this test this week. Scan your next refinement session for UI nouns in the want slot: button, dropdown, modal, panel, tab, toggle. Each entered the backlog without a design review. Rewrite one as the capability it was buying and see whether the room proposes something better.

What each slot is actually claiming

Slot	What it claims	How it fails	The test
As a [role]	A population behaves differently, and the difference changes what "correct" means	Says "user" — true of everyone, so it constrains nothing	Substitute two other roles. If no criterion changes, the role is decoration
I want [capability]	A capability is missing, stated at a level that leaves the how open	Names a control or endpoint — a design promoted to a requirement	Can three different implementations satisfy it? One means it's a design
So that [outcome]	Something observable will differ after release — the only falsifiable clause	Missing, or circular ("so that I can save my searches")	Write the past-tense sentence true if it worked, and the observation that falsifies it
Acceptance criteria	The conditions of satisfaction — where the story stops being negotiable	Contains implementation: elements, endpoints, tables	Per line: what a user observes, or what a developer must do?

Acceptance criteria are the confirmation, not the design

Ron Jeffries described a story as three things — Card, Conversation, Confirmation — and Confirmation is the acceptance test: customer-defined examples that settle ambiguity and demonstrate correct implementation (Jeffries, 2001). The sentence carries intent and stays open; the criteria carry the conditions of satisfaction and are closed. Each half fails in mirror image: the sentence by becoming specific (a button), the criteria by staying vague ("works well") or getting specific about the wrong thing.

Leaked design. The saved-search dropdown appears in the top-right of the filter panel. Selections persist in localStorage. The dropdown lists a maximum of ten entries.

Confirmation. Given an analyst assigned to the disputes queue, when they open the console at the start of a shift, then the defined queue is applied without further selection, and the case set they see is identical to that of any other analyst assigned to the same queue at the same moment.

The first freezes three decisions a developer would have made better into criteria nobody may change without a conversation. The second states an observable outcome — including the consistency property that was the whole point — and leaves storage, layout, and limits to the people who know what they cost. Note what the Given clause does: it forces a pre-state, and that is where unasked data questions live. Given an analyst assigned to the disputes queue only makes sense if queue assignment exists. On REV-118 it didn't, and writing the criterion is what surfaced that.

Criteria appearing on every story — accessible, logged, audited, doesn't break the nightly job — are not acceptance criteria at all. They belong once in the definition of done, where they get maintained instead of copy-pasted and diluted.

Run this test this week. Mark every line in one story's criteria naming a UI element, endpoint, table, or library — each skipped design review. Then mark every line that could not fail: "works as expected," "performance is acceptable." Those assert nothing at all.

The exception: when this is the wrong container

Forcing every piece of work into the template makes it meaningless: a form that fits everything describes nothing. Four cases where a different container is correct:

Spikes. A spike resolves uncertainty, so an outcome clause promising user benefit is a fiction. It needs a time box and the decision it will produce: "Two days, and we'll know whether to use the provider's SDK or write our own." A spike with no named decision is research, and research has no end.

Bugs. A bug already has a role, capability, and outcome — established when the original feature shipped. Restating them loses what matters: observed behaviour, expected behaviour, reproduction steps, and the affected population — how many users, how many records, since when. That last field is the one most bug templates omit and the one that decides priority.

Compliance and contractual work. When behaviour is set by statute, a contract, or an API you don't control, no user's preference is being served. Cite the clause, state the obligation as a rule, record the evidence a reviewer will want. The claim is conformance, verified against a text.

Platform and enabler work. The beneficiary is another engineer, and inventing an end-user one to pass review is lying inside a template. Either name the internal consumer and the decision the work enables, or attach the enabler to the first story that needs it.

A fifth case is about shape rather than type. One long flow with multiple actors, preconditions, and a dozen alternate paths — claims adjudication, payment settlement — loses continuity when chopped into stories. That's what a use case is for.

All five share one thing: the exemption is from the template, not from the claim. A spike has a decision, a bug has an affected population, a compliance item has a clause. Run this test this week: open the ticket templates your team uses and find the falsifiable field in each. A container without one didn't escape the problem — it renamed it.

Run this on your board this week

1. Write the past-tense claim for your ten most recently shipped stories, plus the observation that would falsify each. The ones you can't write were never evaluated.

2. Substitute the role on five in-flight stories. Where swapping it changes nothing, you wrote for an average user with no edge cases.

3. Hunt UI nouns in the want slot and implementation in the criteria. Rewrite one as a capability and let the room propose alternatives.

4. Find the countable claim inside your most-argued story. On REV-118: how many distinct filter combinations are analysts running? Bring the number, not the opinion.

Used as three fields to fill in, the template produces sentences that are always true and never useful, which is how teams ship steadily and learn nothing.

REV-118 was written twice. The first version described a button and could not be wrong. The second described a state of the world — every analyst opening the same defined queue — and was wrong in an expensive, useful way before a line of code existed, because the logs said thirty-one where the team said four. That is the value of the clause everyone deletes: it's the only part of the story that can send you to look at your own data before you build.

Sources

• Mike Cohn, User Stories Applied: For Agile Software Development (Addison-Wesley, 2004) — popularized the three-part template. The As a / I want / so that form originated with Rachel Davies and the team at Connextra in the early 2000s, hence "the Connextra format."

• Ron Jeffries, Essential XP: Card, Conversation, Confirmation, 2001 — the three Cs, and the argument that Confirmation is the acceptance test rather than documentation.

• Bill Wake, INVEST in Good Stories, and SMART Tasks, XP123, 2003 — the six criteria, applied once a story exists.

• Jeff Patton, User Story Mapping (O'Reilly, 2014) — stories as a vehicle for shared understanding rather than a written artifact.

• ISO/IEC/IEEE 29148:2018, Requirements engineering — characteristics of a well-formed requirement, including verifiability.