Guides / Prompting and shipping

How to Write User Stories (with Examples and Acceptance Criteria)

Write user stories developers and AI builders can act on: the As a / I want / So that format, acceptance criteria, splitting, and good vs bad examples.

Mythex Team · 2026-09-29 · 7 min read

A user story is a short description of a feature from the user's point of view: "As a [type of user], I want [goal] so that [reason]." Under it you write acceptance criteria, a few specific conditions that must be true for the story to count as done. Keep each story small enough to build and test in one go, and write the criteria so anyone could check them.

User stories were made popular by agile software teams, but they're just as useful when you're building on your own with an AI app builder. A good story is a good prompt.

The format

A user story has three parts:

As a [who], I want [what] so that [why].

• Who is a specific kind of user: a first-time visitor, a paying member, a clinic receptionist, an admin. Not "the user".
• What is the thing they want to do, in their words. Not how the screen works.
• Why is the outcome they care about. It's the part people skip, and the one that stops you building the wrong thing.

Example:

As a gym member, I want to cancel a class booking from my phone so that someone on the waitlist can take my spot and I'm not charged a no-show fee.

The "why" tells you two things the "what" didn't: it must work on a phone, and the waitlist and the fee rules are involved.

Acceptance criteria

A story says what's wanted. Acceptance criteria say when it's done. They should be specific enough that two people would agree whether each one passes.

A common way to write them is Given / When / Then:

• Given a starting situation
• When the user does something
• Then this is the result

For the gym booking story:

1. Given I have a booking more than 12 hours away, when I tap Cancel and confirm, then the booking is removed and I see "Booking cancelled".
2. Given I cancel a booking and the class has a waitlist, when the cancellation saves, then the first person on the waitlist gets the spot and an email.
3. Given a booking less than 12 hours away, when I tap Cancel, then I see that a late-cancellation fee applies before I confirm.
4. Given I'm on a phone-width screen, then the Cancel button is visible without scrolling sideways.

A plain checklist works too, as long as each item is testable. "Cancelling is easy" is not testable. "Cancel takes at most two taps from the booking list" is.

Step by step: writing a good story

Step 1: Start from a real user and a real problem

Pick one type of user and something they struggle with today. If you've done customer interviews, use their words. "I always forget to cancel and get charged" is a better starting point than "add cancellation feature".

Step 2: Write the one-line story

Fill in the template. If you can't write a convincing "so that", ask whether the feature is needed at all.

Step 3: Add three to six acceptance criteria

Cover the main success case first, then the important variations: a different role, an empty state, a limit, an error. If you're writing more than six, the story is probably too big.

Step 4: Note what's out of scope

One line saves a lot of back and forth: "Out of scope: refunds for paid classes; admins cancelling on behalf of members." It stops the story from growing while you build it.

Step 5: Check it against INVEST

INVEST is a common checklist for good stories. A story should be:

You don't need to score every story. It's most useful when a story feels wrong and you want to know why.

Good and bad examples

How to split a story that's too big

Big stories are where projects stall. Common ways to split:

• By user role. Members cancel their own bookings; staff cancel anyone's.
• By step in the flow. Browse classes; book a class; get a reminder.
• Simple case first. Cancel a free class now; handle fees and refunds in a later story.
• By data variation. Support one location first, several later.
• Happy path, then errors. Build it working, then add the handling for full classes, expired passes, and so on.

Each piece should still be something a user could use and notice.

Using user stories as prompts

A user story with acceptance criteria is very close to a good prompt for an AI app builder. It gives the AI the who, the what, the why and a definition of done. Send one story per message:

As a gym member, I want to cancel a class booking from my phone so that someone on the waitlist can take my spot. Acceptance criteria:

1. Cancel is on each booking in My Bookings, with a confirmation step.
2. Cancelling more than 12 hours before the class just removes the booking.
3. Less than 12 hours before, show "A late-cancellation fee of $5 applies" before confirming, and record the fee on the booking.
4. If the class has a waitlist, the first person gets the spot and an email.
5. Works on a phone-width screen. Out of scope: refunds, staff cancelling for members. Build this, then check each criterion in the preview and tell me which pass.

You can also ask the AI to draft stories from a rough idea, then edit them yourself:

Here's my app idea: [two or three sentences]. Write the user stories for a first version, grouped by user type, each with 3 to 5 Given/When/Then acceptance criteria. Mark which ones are essential for launch and which can wait.

Always read and edit the result. The AI doesn't know your users; you do.

The acceptance criteria also double as your test plan. When the story is built, walk through each criterion yourself. Our guide on testing your app before launch builds on this.

Where user stories fit with other documents

• A product requirements document describes the whole product: the problem, the users, the scope. User stories are the detailed pieces inside it. See how to write a PRD with AI.
• A bug report describes something that's broken against a story that was already built. See how to write a good bug report.
• An MVP is the smallest set of stories that delivers the core value. See what is an MVP.

Common mistakes

• "As a user…" Too vague. Name the actual type of user.
• Skipping "so that". Without the reason, you can't make sensible trade-offs.
• Writing the solution instead of the need. "I want a dropdown" locks in a design before anyone has thought about it.
• Criteria that can't be tested. "Easy", "fast" and "intuitive" are wishes, not criteria.
• Stories that are really epics. "Manage my account" is ten stories.
• Writing every story up front. Write the next few in detail; keep the rest as one-liners until you get to them.

Stories in Mythex

In Mythex, Plan mode is a good place to turn an idea into stories: the agent discusses the approach before editing anything. When a story is ready, switch to Build and paste it in, one story per message. After each one, /test can click through the preview and check the flow, and you can roll back any reply with Revert to this point if it went the wrong way. See effective prompts in the docs, and our guide on writing prompts for AI app builders.

User story checklist

• Names a specific type of user
• Describes a need, not a design
• Includes a real "so that" reason
• Has three to six testable acceptance criteria
• Covers at least one edge case or error
• States what's out of scope
• Small enough to build and test in one go
• Criteria checked after building, one by one