A comprehensive guide to creating well-structured user stories with proper descriptions, acceptance criteria, and business value statements that follow the INVEST principles
This document explains how to create effective user stories in Agile development. User stories represent business value that can be delivered within a single increment and go beyond traditional requirements by specifying not just what is needed, but who needs it and why. A well-structured story includes a clear description using the "As a... I need... So that..." format, documented assumptions, and acceptance criteria written in Gherkin syntax.
User stories represent pieces of business value that a team can deliver within a single completed increment. Unlike traditional requirements that simply state what is needed, user stories provide a more comprehensive view of functionality by including the stakeholder perspective and business value.
Traditional requirements often focus solely on functionality with statements like “The system shall…” or “I need this feature…” User stories, however, include three critical components:
This expanded perspective helps the team understand not just what to build, but the context and value of each feature, leading to better prioritization and implementation decisions.
A well-structured user story contains several key components that provide clarity and context for the development team.
The core of a user story follows a simple but powerful syntax:
1As a [role/persona],
2I need [functionality],
3So that [business value/benefit].
This format ensures that each story captures:
When prioritizing the product backlog, the business value component becomes especially important in determining which stories should be addressed first.
Including relevant assumptions and known details helps developers understand the context and constraints for implementing the story. This section might include:
While this section doesn’t need exhaustive detail, it should contain sufficient information to guide developers and prevent misunderstandings or wasted effort.
Acceptance criteria, also called the definition of done, is critical for establishing when a story is complete. Well-defined acceptance criteria:
Acceptance criteria should be testable, clear, and concise, focusing on observable behaviors rather than implementation details.
Gherkin provides a structured language for describing system behavior in a way that is understandable to both technical and non-technical stakeholders.
Gherkin follows a three-part structure:
| Component | Purpose | Example |
|---|---|---|
| Given | Establishes the precondition or initial context | Given there are 100 customers in the database |
| When | Describes the action or event that occurs | When I request a customer email list |
| Then | Specifies the expected outcome or result | Then I should see a list of 90 customer emails |
This format creates clear, testable scenarios that define the expected behavior of the system. Multiple Given-When-Then blocks can be used for more complex scenarios.
Consider this acceptance criterion for a marketing email feature:
1Given there are 100 customers in the database
2And 90 have opted into email promotions
3When I request a customer email list
4Then I should see a list of 90 customer emails
This clearly communicates that:
The beauty of Gherkin is that both the marketing manager (who needs this feature) and the developer (who will implement it) can understand and agree on exactly what constitutes a completed story.
Here is a complete example of a well-structured user story:
1Title: Customer Email List for Promotions
2
3As a marketing manager,
4I need a list of customer names and emails,
5So that I can notify them of marketing promotions.
6
7Assumptions:
8- We maintain customer emails in the database
9- Customers have opted in to receiving promotions
10
11Acceptance Criteria:
12Given there are 100 customers in the database
13And 90 have opted into email promotions
14When I request a customer email list
15Then I should see a list of 90 customer emails
This story clearly identifies who needs the functionality (marketing manager), what they need (list of customer names and emails), and why (to send promotional notifications). The assumptions provide context, and the acceptance criteria establish a clear definition of done that can be verified.
Bill Wake’s INVEST acronym provides a useful framework for creating high-quality user stories:
| Principle | Description |
|---|---|
| Independent | Stories should be self-contained and not heavily dependent on other stories |
| Negotiable | Details should be flexible and open to discussion |
| Valuable | Each story must deliver value to stakeholders |
| Estimable | Teams should be able to estimate the effort required |
| Small | Stories should be small enough to plan and estimate accurately |
| Testable | Stories must include clear criteria for testing and verification |
While complete independence is not always possible (the example story assumes customer emails exist in the database), teams should strive to minimize dependencies between stories. When dependencies exist, they should be clearly documented in the assumptions section.
Independence allows for more flexible prioritization and planning. Stories that depend on many other stories being completed first are harder to schedule and implement efficiently.
Stories should remain somewhat negotiable rather than being overly prescriptive. This allows the team to collaborate on the best implementation approach while still delivering the core value.
The value component is essential for prioritization. Stories that deliver higher business value generally deserve higher priority in the backlog, making the “so that” portion of the story description particularly important.
For larger pieces of functionality that cannot be completed in a single sprint, Agile teams use epics—collections of related user stories that together deliver a significant feature or capability.
Epics are appropriate when:
Epics provide a way to organize related stories and track progress on larger initiatives while still maintaining the benefits of working with small, manageable user stories.
During backlog refinement, teams progressively break down epics into smaller user stories. This process often reveals new insights about requirements and helps ensure that each resulting story follows the INVEST principles.
Effective user stories form the foundation of successful Agile development by clearly communicating what needs to be built, for whom, and why. By including a clear role-functionality-value description, relevant assumptions, and testable acceptance criteria using Gherkin syntax, teams can ensure shared understanding and avoid misaligned expectations. Following the INVEST principles helps create high-quality stories that can be effectively prioritized, estimated, and implemented. For larger pieces of work, epics provide a way to manage and track progress while maintaining the benefits of working with smaller, focused user stories.
(3) User stories represent pieces of business value that a team can deliver within a single completed increment. They go beyond traditional requirements by specifying not just what is needed, but who needs it (the role/persona) and why (the business value).
(2) Without clear acceptance criteria, there is no shared understanding of what constitutes “done,” leading to misaligned expectations and disputes during the sprint review when stakeholders may reject work that developers thought was complete.
(3) A well-structured user story follows the “As a [role], I need [functionality], So that [business value]” format, which clearly identifies who needs the functionality, what they need, and why they need it.
(4) “But” in Gherkin is not used to add additional functional requirements. It’s actually used as a negative conjunction after “Given,” “When,” or “Then” to add exceptions or negative conditions to a scenario. Additional functional requirements would be separate Given-When-Then blocks or entirely new user stories.
(2) Assumptions in a user story provide important context and constraints that help developers understand implementation considerations, such as technical decisions already made, infrastructure requirements, or dependencies on other systems.
(3) The “I” in INVEST stands for “Independent,” meaning user stories should ideally be self-contained with minimal dependencies on other stories, allowing for more flexible prioritization and implementation.
(4) A detailed technical specification of how to implement the solution is not a key component of a good user story. In fact, user stories should remain somewhat negotiable rather than prescriptive about implementation details, allowing the team to collaborate on the best approach.
| Component | Primary Purpose |
|---|---|
| Role (“As a…”) | Identifies who will benefit from the functionality |
| Functionality (“I need…”) | Describes what capability is required |
| Business Value (“So that…”) | Explains why the functionality matters and helps with prioritization |
| Acceptance Criteria | Establishes clear, testable conditions for completion |
| Assumptions | Provides context and known constraints for implementation |
Understanding the purpose of each component helps teams create comprehensive, effective user stories that clearly communicate requirements and expectations.
(2) Clear, testable acceptance criteria are the first thing to check when evaluating if a story is ready for development, as they define what constitutes completion and prevent misunderstandings during implementation.
(3) An Epic should be used instead of a standard user story when the functionality is too large to be completed within a single sprint. Epics represent larger pieces of work that need to be broken down into smaller, manageable user stories.
The Gherkin “And” keyword can be used after any of the Given, When, or Then statements to add additional context, actions, or expectations.
True. The “And” keyword in Gherkin can follow any of the main keywords (Given, When, Then) to provide additional context, actions, or expectations that belong to the same category as the preceding statement. This allows for more comprehensive and readable acceptance criteria.
A user story can be considered “Independent” according to INVEST principles even if it has some technical dependencies on other stories.
True. While complete independence is ideal, it’s often unrealistic in complex systems. A story can still be considered sufficiently “Independent” for INVEST purposes if its business value can be delivered without requiring other stories to be completed first, even if there are some technical dependencies that need to be managed.
The “So that…” portion of a user story is optional if the business value is obvious to everyone.
False. The “So that…” portion should never be considered optional, even if the value seems obvious. Making the business value explicit helps with prioritization, prevents misunderstandings, and ensures that everyone understands why the functionality matters. What seems obvious to one person may not be to others.
(2) The correct sequence is Feature → Epics → User stories → Technical tasks. Teams start with a large feature, break it down into epics that represent major components, further divide these into user stories that can be completed in a single sprint, and finally define the technical tasks needed to implement each story.
| Gherkin Keyword | Appropriate Usage |
|---|---|
| Given | Setting up a test user account with admin privileges |
| When | Clicking the “Export Data” button in the admin panel |
| Then | Verifying that a CSV file containing user data is downloaded |
| And | Adding that the file contains all 50 user records after “Then” |
| But | Specifying that user passwords are not included in the export |
Proper usage of Gherkin keywords ensures clear, unambiguous acceptance criteria that can be easily automated in behavior-driven development testing frameworks.
| INVEST Principle | Problem It Prevents |
|---|---|
| Independent | Blocked implementation due to dependencies on other unfinished stories |
| Negotiable | Rigid specifications that don’t allow for collaborative problem-solving |
| Valuable | Implementation of features that don’t address user or business needs |
| Estimable | Inability to plan sprints due to unclear scope |
| Small | Incomplete stories that span multiple sprints |
| Testable | Disputes about whether a story is actually completed |
Understanding the problems each INVEST principle prevents helps teams create more effective user stories that facilitate smoother development cycles.
(2, 4) User stories focus on business value delivered to stakeholders and help create a shared understanding between technical and non-technical team members. They should not typically include technical implementation details (which contradicts their negotiable nature) and they do not replace the need for technical documentation (which serves different purposes).
The correct order is 2→3→4→1. A well-structured user story document typically begins with a title (2), followed by the “As a… I need… So that…” statement (3), then any assumptions and details (4), and finally the acceptance criteria (1) that define when the story is complete.
Scenario - A marketing manager needs to be able to segment customers based on their purchase history for targeted email campaigns.
(2) Option 2 provides the most appropriate acceptance criteria for the scenario. It directly addresses the functionality needed (customer segmentation based on purchase history) with a specific example that can be tested. The other options are either too vague or address different functionality than what’s described in the scenario.
“The system needs a better user interface with improved functionality for administrators and regular users that makes it easier to use and more efficient.”
All options (1-5) identify valid issues with this ineffective user story. It lacks the “As a [role]” (1), doesn’t specify what functionality is needed beyond vague “improved functionality” (2), provides no clear business value (3), contains multiple requirements for different user types suggesting it’s too large (4), and offers no testable criteria with its vague “better” and “improved” language (5).
(2) The most appropriate response is for the team to collaborate to find a solution that delivers the business value while respecting technical constraints. User stories are intentionally “Negotiable” (the N in INVEST) to allow for this type of collaborative problem-solving between product owners and development teams.