User Story

For a long time the standard way to write down what to build was a feature list. "Add search filters." "Support file upload." "Settings screen for notifications." A tidy column of system capabilities handed to engineering. The list was easy to read and it had no people in it.

The gap shows up the moment someone starts building. An engineer holding the line "support file upload" asks what the size limit should be. Whoever wrote the line isn't in the room, and if they are, the answer is "whatever seems reasonable." Nothing in the sentence says who uploads what or why, so there is no basis for picking a number. If the person is attaching a scanned contract, 5MB is plenty. If they're uploading a recorded meeting, 500MB isn't enough. One line was quietly standing in for two completely different features.

Feature lists also fail at prioritization. Ask whether search filters or notification settings should come first and the discussion turns into a contest of preferences, because neither line says whose problem it removes. The item belonging to whoever argues hardest moves up, and nobody can explain afterward why the other one slipped.

Spend two months like that and what ships is usually something nobody asked for. The engineer decided against an imagined user, the person who wrote the line had a different user in mind, and there was no point at which the two versions met. "That isn't what I meant" arrives on the day the screen is first demoed, by which time undoing the work costs about what building it did. The feature list gave nobody an early chance to notice the mismatch, because a list of capabilities reads the same to two people who picture two different users.

The large container for the same requirements is the product requirements document (PRD), which records what is being built, why, and where the finish line is. That document can run thirty pages. It isn't a size any one person finishes in a week, so it has to be broken up — and breaking it up is exactly where teams slide back into feature lists.

A user story is a format that forces the breakdown to happen around a person instead. Each line splits into three parts: who, what they want to do, and what they get out of it. The earlier example becomes "as a sales rep, I want to attach a signed contract scan to a document, so that every customer's paperwork sits in one place." Written that way, the size-limit question already carries its own answer. Stories broken out like this stack up in priority order in the product backlog, and the team pulls from the top.

Working with user stories means knowing three branches: what a story is made of, how to judge whether a story is any good, and how to lay many stories out at once to see the whole picture.

The first branch covers the parts of a single story. The sentence has three slots and a fourth one hangs underneath it.

1. Who — the person using this, named as a role. "As a user" narrows nothing, so go one level down: "as a team lead who just signed up," "as the person who handles billing." The tighter this slot, the sharper the other two become on their own.
2. What they want to do — the action the person is taking, not a screen or a button. "Add a toggle to the settings page" is the builder's language. "Turn off notifications on weekends" is the user's.
3. What they get out of it — the purpose behind the action. This is the slot people skip most often, and skipping it closes off every alternative solution. If the purpose reads "I don't want to be interrupted on weekends," someone can suggest quiet-hours scheduling instead of a toggle, and the team compares two options against the same stated goal rather than arguing about which control looks better.
4. Acceptance criteria — the checks attached below the sentence, written so they can be verified. For the example: "with the weekend setting on, no notifications are sent on Saturday or Sunday," and "the setting is stored per account and persists on other devices."

The three slots say why the work matters. The fourth says when it's over. With only the first three, the team knows the direction but can't call anything done. With only the fourth, there's a checklist and no reason behind it.

The second branch is about judging a story, and two different standards apply at two different moments.

1. INVEST — applied before the story goes into the backlog. It asks six questions: is the story independent, negotiable, valuable, estimable, small, and testable. Size is what fails most often. "The whole payments feature" is not a story, it's something still waiting to be split. Independence fails nearly as often: two stories where A must finish before B can start can't be reordered, which shrinks the options when planning.
2. Definition of done (DoD) — applied after the story is built. Acceptance criteria differ story by story; the definition of done is the shared bar every story clears. Reviewed, tested, running in production. Work that passes its acceptance criteria but skips the definition of done looks finished on screen and sits undeployed. A weekend toggle that works on the engineer's machine has met its acceptance criteria and none of the shared bar.

The third branch is about seeing stories together. Story mapping lays the user's end-to-end flow across a horizontal axis and stacks the stories for each step underneath it. For a collaborative document product the horizontal axis might read: sign up, create a document, invite a teammate, edit together, share outward. Stack the stories and it becomes visible that the invite column holds twelve of them while the sharing column holds none — a hole a flat list never reveals. Draw a horizontal line near the top and build only what sits above it, and the result is a first version where every step works at a minimum level. Cut the map vertically instead, shipping a perfect invite feature, and users get a product that lets them call a colleague in but not work with them. The horizontal cut gives up depth in every step; the vertical one gives up whole steps, which is the one users notice.

The three branches run in order. Write a line with the first, filter it with the second, spread the lines out with the third to find what's missing. Teams that are good at stories aren't the ones who memorized the sentence template; they're the ones who run all three steps.

"Could you rewrite this as a story? There's no one in it, so I can't tell what to build."

The request arrived as a feature name, which leaves too little to judge by.

"This story has no acceptance criteria. What does finished look like?"

Nobody has agreed on how completion gets decided, so settle it before writing code.

"This story is too big. Let's split it in two."

It can't finish inside one cycle, and carrying it as is will push the plan.

The week Pagedeck reworked notification settings, Mia brought in eight stories. During sprint planning, Theo pointed at one of them: "as a team admin, I want to manage notification rules." Manage turned out to mean different things to different people. Theo read it as switching rules on and off. Mia had written it meaning an admin could change other members' rules for them. The distance between those two readings was two days of work versus two weeks, and neither of them had any way of discovering that from the sentence alone.

The story split into three right there: turning off your own notifications, setting a team default, and viewing another member's settings. Once each had acceptance criteria attached, it was clear the third one ran into permissions and couldn't fit in the cycle, so the plan took the first two. Story points — the relative size assigned to a piece of work — only became possible after the split. Nobody could put a number on the original line, because a two-day job and a two-week job were sharing one sentence. Estimates that feel impossible to give are often a sign that a story is still carrying more than one story inside it.

Mia's habit afterward wasn't to write longer sentences but to narrow the role slot one more notch. "As a team admin" became "as the admin of a team of ten or more," and the same kind of question stopped coming back. A narrower role drags the rest along with it: how often that person opens the screen, and what they're stuck on.

The most common mistake is treating the format as the substance. The template has three slots, so filling the slots looks like writing a story. But "as a user, I want to log in, so that I can log in" fills all three and narrows nothing — the role is everyone and the purpose just repeats the action. A backlog full of lines like that carries exactly as much information as the old feature list did, and the team has spent extra hours to arrive at the same standstill. There's a quick test: delete the role slot and read the sentence again. If it still reads fine, that slot was empty. The same test works on the purpose slot, which passes only when it names something outside the product.

The second mistake is reading a story as a document. One line written down looks like a specification of record. The format was designed from the start as a marker for a conversation. Holding little information isn't a flaw in it, it's the intent, and the rest gets filled in face to face by the person who wants it and the person building it, right before the work starts. Skip that conversation and hand over the line alone, and you get the notification-rules situation above: two people reading one sentence differently for two weeks. This is also why acceptance criteria keep growing in teams that trade stories only in writing. What a conversation would settle gets pushed into text, twenty checks pile up under a single story, and at that point it's indistinguishable from the specification document it replaced.