How to Write Perfect User Stories in English

User stories are the most common format for capturing software requirements in agile teams. A well-written user story communicates who needs something, what they need, and why — clearly enough that a developer can build it, a tester can verify it, and a stakeholder can confirm it. This guide covers the structure, vocabulary, and common pitfalls for writing user stories in English.

---

The Standard User Story Format

The Three-Part Formula

The classic user story follows this template:

As a [type of user], I want to [action], so that [benefit or outcome].

This format has three intentional parts:

1. “As a [type of user]” — identifies who the feature serves
2. “I want to [action]” — describes what the user needs to do
3. “So that [outcome]” — explains why — the business or user value

Examples:

“As a registered customer, I want to save my payment method, so that I can check out faster on future purchases.”

“As an admin, I want to export user activity logs to CSV, so that I can generate compliance reports for the auditor.”

“As a mobile app user, I want to receive push notifications for order updates, so that I know when my delivery is en route.”

---

Choosing the Right User Type

The user type should be specific and meaningful — not a generic placeholder.

❌ “As a user…” — too vague; almost every story would say this. ✅ “As a first-time buyer…” ✅ “As a team administrator…” ✅ “As an unauthenticated visitor…” ✅ “As a support agent handling escalations…”

The more specific the user type, the more clearly the story communicates scope and priority.

---

Writing the Action Clause

The action clause should describe what the user wants to do — not how the system implements it.

❌ “I want a modal dialog to appear when I click the button” — describes implementation ✅ “I want to add items to my wishlist” — describes user intent

Useful action verbs:

• view, see, access, browse — reading/consuming
• search, filter, sort — discovery
• create, add, upload, submit — creation
• edit, update, modify — modification
• delete, remove, archive — deletion
• receive, be notified — system-to-user communication
• export, download — data extraction

---

Writing the Benefit Clause

The so that clause is the most important and most frequently omitted part. It anchors the story in business value and helps the team understand why the feature exists.

❌ “As a project manager, I want to see all open tasks, so that I can.” — incomplete ✅ “As a project manager, I want to see all open tasks, so that I can identify blockers and reassign work before the deadline.”

If you can’t articulate the so that, question whether the story is worth building.

---

Acceptance Criteria

Acceptance criteria (AC) define the specific conditions that must be true for the story to be considered done. They turn a vague story into a testable specification.

Gherkin Format (Given / When / Then)

When precision matters, write AC in the Gherkin format:

Given [precondition or context]
When [action is performed]
Then [expected outcome]

Example:

Story: As a registered customer, I want to save my payment method,
       so that I can check out faster on future purchases.

Acceptance Criteria:

Scenario 1: Save a new card
  Given the customer is logged in and viewing the checkout page
  When they enter valid card details and check "Save for future use"
  Then the card is saved to their account
  And they see a confirmation message

Scenario 2: Use a saved card
  Given the customer has a saved card on file
  When they view the checkout page
  Then the saved card is displayed as the default payment option
  And they can complete checkout without re-entering card details

Scenario 3: Delete a saved card
  Given the customer has at least one saved card
  When they navigate to Account > Payment Methods and click "Remove"
  Then the card is removed from their account
  And is no longer displayed at checkout

Bulleted Acceptance Criteria

For simpler stories, plain bullet points work well:

Acceptance Criteria:
- The filter applies within 300ms of the user's selection
- Filter state is preserved when the user navigates back to the list
- A "No results" message appears if no items match the filter
- The filter can be cleared with a single click
- Filter options are sorted alphabetically

---

The INVEST Criteria

Well-written user stories satisfy the INVEST criteria:

Letter	Meaning	What it means in practice
I	Independent	Can be developed and delivered without being blocked by another story
N	Negotiable	The implementation details can be discussed and adjusted
V	Valuable	It delivers value to a user or the business
E	Estimable	The team can estimate effort for it
S	Small	Can be completed in a single sprint
T	Testable	Acceptance criteria can be written for it

“This story doesn’t meet the INVEST criteria — it’s not estimable because we don’t understand the third-party API constraints. We need a technical spike first.”

---

Common Mistakes in User Stories

1. Technical implementation in the story

❌ “As a user, I want the system to call the /api/v2/users endpoint with a JWT…” ✅ “As a user, I want my session to persist after closing the browser tab…”

2. Multiple stories in one

❌ “As a user, I want to register, log in, and manage my profile…” ✅ Split into three separate stories.

3. Missing acceptance criteria

A story without AC is ambiguous. Even a two-bullet AC is better than none.

4. Describing system behaviour, not user need

❌ “As the system, I want to send an email notification…” ✅ “As a customer, I want to receive an email confirmation after placing an order…”

---

Useful Phrases for Story Refinement

Questioning scope:

• “Can we break this story down into smaller deliverables?”
• “Is this dependency blocking us, or can we decouple the stories?”

Clarifying acceptance criteria:

• “What’s the expected behaviour when the user doesn’t have permission?”
• “Does this need to handle the offline state, or is a network connection assumed?”
• “What’s the edge case when the list is empty?”

Pushing back on vague stories:

• “We can’t estimate this story until we know the ‘so that’ — what value does this deliver?”
• “This story doesn’t have testable acceptance criteria. Can we define them before we pull it into the sprint?”

---

Practice

Test your user story vocabulary with the Business Analyst English exercise set.

See all resources for BAs on the Business Analyst learning path.

Navigating Nuances: English for International Teams

Writing effective user stories is a cornerstone of agile development, but the subtleties of professional English can often trip up developers from around the world. It’s not just about conveying what needs to be built; it’s about doing so with precision and clarity that minimizes ambiguity and fosters seamless collaboration within diverse teams. Many non-native speakers find themselves hesitant to contribute fully, fearing misinterpretations or perceived errors in their writing. Let’s address some specific areas where careful phrasing can make a significant difference.

One common hurdle is the use of conditional language – phrases like “should,” “could,” and “might.” While perfectly acceptable in casual conversation, these words introduce uncertainty that can lead to scope creep during development. Instead of saying “The user should be able to reset their password,” consider “The user can initiate a password reset process via email verification.” The latter is more definitive and actionable for the development team. Similarly, when describing acceptance criteria, avoid statements like “It might display correctly on mobile.” Replace this with “The UI will render consistently across iOS and Android devices at a minimum resolution of 375x667 pixels.” This provides concrete expectations rather than relying on vague possibilities.

Another area ripe for improvement is the use of passive voice, which can obscure responsibility. A typical PR description might read: “The data was validated by the system.” This hides who performed the validation. Rewrite it as: “The system automatically validates the data against predefined rules.” This clearly assigns accountability and demonstrates a deeper understanding of the process. Furthermore, be mindful of idioms and colloquialisms; phrases like “thinking outside the box” or “low-hanging fruit” can easily be misunderstood by those unfamiliar with their specific connotations.

Finally, don’t hesitate to ask for clarification. If you’re unsure about a particular phrase or term, always seek feedback. A quick Slack message asking, “Could you explain what you mean by ‘deliverable’ in this context?” is far more effective than silently struggling to interpret the meaning and potentially introducing errors into your user story. Remember, the goal isn’t to sound perfectly fluent; it’s to communicate effectively and build a shared understanding within your team. Focus on clear, concise language backed by specific details – that’s how you truly write perfect user stories.