How to Write User Stories Developers Understand in 5 Steps

A feature request usually reaches a developer in one of two shapes. Either it is a solution ("add a dropdown on the settings page") with the problem left out, or it is a wish ("people should be able to save things") with no way to tell when it is finished. Both get built, and both get built wrong often enough that the rework costs more than the feature did. A user story is the short piece of writing that prevents that: what a user is trying to do, why, and how everyone on the team will know it works.

This guide is for founders and CTOs who write tickets themselves, or who review the backlog a product owner hands to the engineers. It covers the three-part story format, the Given / When / Then format for acceptance criteria, two worked examples, and the INVEST checklist teams use to verify a story is ready before a sprint starts. If you already have a project brief, stories are the next level down: the brief says what the product is for, the stories say what each slice of it does. A short quiz at the end checks whether the format stuck.

Step 1: agree on what a user story is before writing one

When a team works in sprints, the product's features and requirements get broken down into user stories, and everything downstream hangs off them: estimation, sprint planning, testing, the demo at the end. So before writing the first one, it is worth agreeing on what the object actually is. A user story has four properties:

1. It is written from the user's point of view. Not the database, not the API, not the admin panel: the person using the product and what they are trying to get done.
2. It covers a small slice of functionality that is useful on its own. If the slice delivers nothing until three other slices ship, it is not a story yet; it is a piece of one.
3. It is brief. The traditional test is that the description fits on an index card. If it needs a scroll bar, it is doing too much.
4. It is written plainly enough for everyone to read. The developer, the designer, the tester and the founder should all understand it without a translation.

And there is one thing a story must not contain: the solution. A story describes the outcome the user needs. How to reach it, which component, which table, which endpoint, is the team's call, and writing it into the story takes away the developer's room to find a better route. Heavy technical detail has the same effect, and it also breaks property four, because half the room can no longer read the card.

For founders this last point is the one to watch. It is tempting to write "add a favorites table and a heart icon" because the design is already in your head. Write what the user gets instead, and let the how come out of the conversation with the engineer.

Step 2: write the story in three clauses: who, what, why

The format is a single sentence with three parts:

As a <user role>, I want to <action>, so that <value>.

Here it is filled in for a podcast app: As a podcast listener, I want to mark shows as favorites, so that I can build my own list of shows to come back to.

Each clause answers a question the developer would otherwise have to ask, or guess:

• "As a" answers who. The role or persona: a podcast listener, not "a user". The role tells the engineer whose problem is being solved, which decides where the feature lives and what that person already knows how to do.
• "I want to" answers what. The action, in the user's own vocabulary. Marking a show as a favorite is something a listener does; inserting a row is not.
• "So that" answers why. The value the user gets. It is the clause most often dropped and the most useful one: if the point is a personal list of shows, the developer knows a list view has to exist. Change the why and the right build changes with it.

In practice, writing one goes like this:

1. Name the role precisely. If two different people would want this for different reasons, you may have two stories.
2. State one action. A story with "and" in the I-want clause is usually two stories.
3. Finish with the outcome the user is after. If you cannot write a so-that clause, ask whether the story should exist at all.

Step 3: add acceptance criteria in Given / When / Then

A story says what the user wants. It does not yet say when the team can call it done. That is the job of the acceptance criteria: the conditions that tell the developer, the tester and you that the story is complete. Several formats exist. One that is widely used, because it reads like a test, is Given / When / Then:

• Given is the context or precondition: the state the product is in before anything happens.
• When is the action the user carries out.
• Then is the observable outcome: what the user can see or check afterwards.

For the podcast story:

Given the app is showing a list of podcasts
When I tap the favorite icon next to one of them
Then that podcast is saved
And it appears in my favorites list

The And line is how you attach an extra condition or an extra result without starting a new scenario. Here it does real work: "is saved" on its own is not something a user can see, so the And line adds the visible consequence, and that is what the tester will actually check.

Three habits make the criteria useful rather than decorative:

1. Start from the story, not from the screen. The criteria describe the outcome the so-that clause promised, not the pixels.
2. Write the precondition honestly. If the feature only works for a logged-in listener, the Given line says so. A missing precondition is a bug report waiting to happen.
3. Make every Then line something a person can observe. Each line should be checkable as pass or fail. "Works correctly" is neither.

Step 4: run a second story so the pattern sticks

Both formats are simple, and that is precisely why teams write them badly: the format looks obvious, so nobody practices it. A second example, this time a job board:

As a job seeker on LinkedIn, I want to filter my search to remote-only positions, so that I can apply for roles I can do from anywhere.

And its criteria:

Given I am on the Jobs tab
When I run a search
And I filter the results to remote only
Then only remote positions are listed
And I can apply to any of them from the results

Notice what this second example adds. There are now two And lines, one on the When side (a second action, the filter) and one on the Then side (a second outcome, being able to apply). The scenario is still one scenario; the And lines just let it hold more than one step. Notice also what is absent: nothing about how the filter is implemented, what the search query looks like, or which component renders the list. The developer decides those.

A useful exercise before the next planning meeting: take the last three tickets in your tracker and rewrite each one in this shape. Tickets that cannot produce a so-that clause are usually tasks wearing a story's clothes, and tickets that cannot produce a Then line are not ready to be built.

Step 5: check the story against INVEST before it enters a sprint

You now have a story and its criteria. How do you know it is a good one, and not just a correctly formatted one? The check most agile teams use is the acronym INVEST, six adjectives a story should satisfy:

• Independent. The story is not coupled to another story. It can be built in any order and released on its own.
• Negotiable. The goal is fixed; the way of reaching it is open to discussion between you and the team. This is step 1's "no solution in the story" rule, seen from the other side.
• Valuable. Every story that ships should make the product more valuable. The so-that clause is where that value is stated.
• Estimable. The team can put a size on it. That requires enough detail in the card to plan around, which is what lets them commit to it in a sprint.
• Small. It can be finished within one sprint. The smaller the story, the easier it is to size and to test.
• Testable. It can be tested in a binary way: the associated tests pass or they fail. A story that is testable is, almost by definition, a story with good acceptance criteria.

Use it as a gate, not as a scorecard. Before sprint planning, run every candidate story down the six letters. A story that fails one goes back to whoever wrote it, with a specific fix: split it (Small, Independent), add the why (Valuable), strip the implementation detail out (Negotiable), add context (Estimable), or write the missing criteria (Testable). What does not happen is the developer starting work on a story that failed the check and discovering the gap mid-sprint.

Common mistakes when founders write the stories themselves

• Writing the solution instead of the need. "Add a heart icon to each row" is a design decision, not a story. State what the listener wants and why; the icon may or may not be the answer.
• Dropping the so-that clause. Without the why, the story fails the Valuable check and the developer has no way to judge trade-offs. If the why is hard to write, that is information.
• Stories that are really projects. "As a user, I want an account" will not fit in a sprint. Split it until each piece delivers something on its own and can be estimated.
• Stories that only make sense together. If story B is useless until story A ships, they are not independent and cannot be planned or released separately.
• Criteria nobody can check. "The page should feel fast" or "the list looks good" cannot pass or fail. Rewrite them as observable outcomes.
• Writing for the engineer only. A card full of table names and endpoints fails the "understood by everyone" property. If the designer and the tester cannot read it, it is not done.

One sentence, a few lines of criteria, six checks

That is the whole method. The story is one sentence from the user's point of view: who, what, why. The acceptance criteria say when it is done: Given the context, When the action, Then the observable result, with And lines for anything extra. INVEST is the gate before planning: Independent, Negotiable, Valuable, Estimable, Small, Testable. None of it takes long to write. What takes practice is keeping the solution out of the card and the why in it.

If nobody on the team owns the backlog yet, this is the job a product owner does all day: turning requests into stories a developer can pick up without a meeting. We match US startups with vetted remote product owners and scrum masters; see how it works.