What makes a good user story? The three-line anatomy

A user story is not documentation, it is a placeholder for a conversation. But a sloppy placeholder starts a sloppy conversation. The template, the INVEST test, and Given/When/Then acceptance criteria keep every blank honest.

The template

As a ⟨role⟩,          -- who benefits, never just "user"
I want ⟨capability⟩,  -- what they can do, not which widget
so that ⟨outcome⟩.    -- the value; if empty, why build it?

The template is not bureaucracy. Each blank is a question someone forgot to answer:

• Role: who exactly? "User" means you have not decided.
• Capability: what can they do afterward that they cannot do now? Widgets and dropdowns do not belong here.
• Outcome: the why. If the "so that" is empty, the story is a task wearing a story costume.

The INVEST test

• Independent: ships without waiting on another story
• Negotiable: a conversation starter, not a contract
• Valuable: a real someone wants the outcome
• Estimable: the team can size it
• Small: days, not weeks
• Testable: done is provable, not debatable

Six letters that catch 90% of bad stories before the sprint does.

Acceptance criteria

Given ⟨context⟩,
When ⟨action⟩,
Then ⟨observable result⟩.

One scenario per criterion; edge cases get their own. If you cannot write the Then as something observable, the story is not testable yet.

Bad to good

Bad: "Add export button". A solution with no who and no why.

Good: "As an analyst, I want to export filtered results to CSV, so that I can share them in my weekly report."

Same feature, but now the team knows who it serves, what matters (the filters must survive the export), and when it is done.

The trap: the disguised spec

"As a user, I want a dropdown" is a UI spec wearing a story costume. The smell: the role is "user" and the want is a widget. The fix: ask who exactly, and what outcome they get. The widget moves to acceptance criteria; the outcome stays in the story. Stories describe problems worth solving; solutions belong to the team.