Requirements define the problem space. They capture what the system must do and what the user actually needs to achieve. We care about them for several key reasons:

• Defining “Correctness”: A requirement establishes the exact criteria for whether an implementation is successful. Without clear requirements, developers have no objective way to know when a feature is “done” or if it actually works as intended.
• Building the Right System: You can write perfectly clean, highly optimized, bug-free code—but if it doesn’t solve the user’s actual problem, the software is useless. Requirements ensure the engineering team’s efforts are aligned with user value.
• Traceability and Testing: Good requirements allow developers to write clear acceptance criteria and enable traceability – the ability to link implemented features back to the requirements that motivated them. This supports impact analysis when requirements change and helps verify that the system delivers what was requested.

Requirements vs. Design

In software engineering, distinguishing between requirements and design is critical to building successful systems. Requirements express what the system should do and capture the user’s needs. The goal of requirements, in general, is to capture the exact set of criteria that determine if an implementation is “correct”.

A design, on the other hand, describes how the system implements these user needs. Design is about exploring the space of possible solutions to fulfill the requirements. A well-crafted requirements specification should never artificially limit this space by prematurely making design decisions. For example, a requirement for pathfinding might be: “The program should find the shortest path between A and B”. If you were to specify that “The program should implement Dijkstra’s shortest path algorithm”, you would over-constrain the system and dictate a design choice before development even begins.

Examples

Here are some examples illustrating the difference between a requirement (what the system must do to satisfy the user’s needs) and a design decision (how the engineers choose to implement a solution to fulfill that requirement):

• Route Planning
  • Requirement: The system must calculate and display the shortest route between a user’s current location and their destination.
  • Design Decision: Implement Dijkstra’s algorithm (or A* search) to calculate the path, representing the map as a weighted graph.
• User Authentication
  • Requirement: The system must ensure that only registered and verified users can access the financial dashboard.
  • Design Decision: Use OAuth 2.0 for third-party login and issue JSON Web Tokens (JWT) to manage user sessions.
• Data Persistence
  • Requirement: The application must save a user’s shopping cart items so they are not lost if the user accidentally closes their browser.
  • Design Decision: Store the active shopping cart data temporarily in a Redis in-memory data store for fast retrieval, rather than saving it to the main relational database.
• Sorting Information
  • Requirement: The system must display the list of available university courses ordered alphabetically by their course name.
  • Design Decision: Use the built-in TimSort algorithm in Python to sort the array of course objects before sending the data to the frontend.
• Cross-Platform Accessibility
  • Requirement: The web interface must be fully readable and navigable on both large desktop monitors and small mobile phone screens.
  • Design Decision: Build the user interface using React.js and apply Tailwind CSS to create a responsive, mobile-first grid layout.
• Search Functionality
  • Requirement: Users must be able to search for specific books in the catalog using keywords, titles, or author names, even if they make minor typos.
  • Design Decision: Integrate Elasticsearch to index the book catalog and utilize its fuzzy matching capabilities to handle user typos.
• System Communication
  • Requirement: When a customer places an order, the inventory system must be notified to reduce the stock count of the purchased items.
  • Design Decision: Implement an event-driven architecture using an Apache Kafka message broker to publish an “OrderPlaced” event that the inventory service listens for.
• Password Security
  • Requirement: The system must securely store user passwords so that even if the database is compromised, the original passwords cannot be easily read.
  • Design Decision: Hash all passwords using the bcrypt algorithm with a work factor (salt) of 12 before saving them to the database.
• Real-Time Collaboration
  • Requirement: Multiple users must be able to view and edit the same code file simultaneously, seeing each other’s changes in real-time without refreshing the page.
  • Design Decision: Establish a persistent two-way connection between the clients and the server using WebSockets, and use Operational Transformation (OT) to resolve edit conflicts.
• Offline Capabilities
  • Requirement: The mobile app must allow users to read previously opened news articles even when they lose internet connection (e.g., when entering a subway).
  • Design Decision: Cache the text and images of recently opened articles locally on the device using an SQLite database embedded in the mobile application.

Practice: Requirement or Design?

Use the quiz below to practice the boundary: a requirement should describe the outcome the system must satisfy, while a design decision chooses the mechanism used to satisfy it.

Why Does the Difference Matter?

Blurring the lines between requirements and design is a common mistake that leads to misunderstandings. In practice, the two are often pursued cooperatively and contemporaneously, yet the distinction matters for three main reasons:

Avoiding Premature Constraints: When you put design decisions into your requirements, you artificially limit the space of possible solutions before development even begins. If a product manager writes a requirement that says, “The system must use an SQL database to store user profiles”, they have made a design decision. A NoSQL database or an in-memory cache might have been vastly superior for this specific use case, but the engineers are now blocked from exploring those better options.

Preserving Flexibility and Agility: Design decisions change frequently. A team might start by using one sorting algorithm or database architecture, realize it doesn’t scale well, and swap it out for another. If the requirement was strictly about the “what” (e.g., “Data must be sorted alphabetically”), the requirement stays the same even when the design changes. This iterative process of swinging between requirements and design helps manage the complexity of what Rittel and Webber termed “wicked” problems (Rittel and Webber 1973) – problems where understanding the requirements depends on exploring the solution. If the design was baked into the requirement, you now have to rewrite your requirements and change your acceptance criteria just to fix a technical issue.

Utilizing the Right Expertise: Requirements are typically driven by the customer or product manager / product owner — the people who understand the business needs. Design decisions are typically led by the software engineers and architects — the people who understand the technology. However, effective teams involve users in design validation (through prototyping and user testing) and engineers in requirements discovery (since technical possibilities shape what can be offered). Mixing the two without clear awareness often results in non-technical stakeholders dictating technical implementations, which rarely ends well.

In short: Requirements keep you focused on delivering value to the user. Leaving design out of your requirements empowers your engineers to deliver that value in the most efficient and technically sound way possible.

Requirements Specifications

User Stories

Quality Attribute Scenarios

Quality attribute requirements (such as performance, security, and availability) are often best captured via “Quality Attribute Scenarios” to make them concrete and measurable (Bass et al. 2012).

Formal Requirements Specifications

Requirements Elicitation

User stories are the most commonly used format to specify requirements in a light-weight, informal way (particularly in projects following Agile processes). Each user story is a high-level description of a software feature written from the perspective of the end-user.

User stories act as placeholders for a conversation between the technical team and the “business” side to ensure both parties understand the why and what of a feature.

Format

User stories follow this format:

As a [user role],

I want [to perform an action]

so that [I can achieve a goal]

For example:

(Smart Grocery Application): As a home cook, I want to swap out ingredients in a recipe so that I can accommodate my dietary restrictions and utilize what I already have in my kitchen.

(Travel Itinerary Planner): As a frequent traveler, I want to discover unique, locally hosted activities so that I can experience the authentic culture of my destination rather than just the standard tourist traps.

This structure helps the team identify not just the “what”, but also the “who” and — most importantly — the “why”.

The main requirement of the user story is captured in the I want part. The so that part primarily clarifies the goal the user wants to achieve. While it should not prescribe implementation details, it may implicitly introduce quality constraints or dependencies that shape the acceptance criteria.

Be specific about the actor. Avoid generic labels like “user” in the As a clause. Instead, name the specific role that benefits from the feature (e.g., “job seeker”, “hiring manager”, “store owner”). A precise actor clarifies who needs the feature and why, helps the team understand the context, and prevents stories from becoming vague catch-alls. If you find yourself writing “As a user”, ask: which user?

Acceptance Criteria

While the story itself is informal, we make it actionable using Acceptance Criteria. They define the boundaries of the feature and act as a checklist to determine if a story is “done”. Acceptance criteria define the scope of a user story.

They follow this format:

Given [pre-condition / initial state]

When [action]

Then [post-condition / outcome]

For example:

(Smart Grocery Application): As a home cook, I want to swap out ingredients in a recipe so that I can accommodate my dietary restrictions and utilize what I already have in my kitchen.

• Given the user is viewing a recipe’s ingredient list, when they select a specific ingredient, then a list of viable alternatives should be suggested.
• Given the user selects a substitute from the alternatives list, when they confirm the swap, then the recipe’s required quantities and nutritional estimates should recalculate and update on the screen.
• Given the user has modified a recipe with substitutions, when they save it to their cookbook, then the customized version of the recipe should be stored in their personal profile without altering the original public recipe.

These acceptance criteria add clarity to the user story by defining the specific conditions under which the feature should work as expected. They also help to identify potential edge cases and constraints that need to be considered during development. The acceptance criteria define the scope of conditions that check whether an implementation is “correct” and meets the user’s needs. So naturally, acceptance criteria must be specific enough to be testable but should not be overly prescriptive about the implementation details, not to constrain the developers more than really needed to describe the true user need.

Here is another example:

(Travel Itinerary Planner): As a frequent traveler, I want to discover unique, locally hosted activities so that I can experience the authentic culture of my destination rather than just the standard tourist traps.

• Given the user has set their upcoming trip destination to a city, when they browse local experiences, then they should see a list of activities hosted by verified local residents.
• Given the user is browsing the experiences list, when they filter by a maximum budget of $50, then only activities within that price range should be shown.
• Given the user selects a specific local experience, when they check availability, then open booking slots for their specific travel dates should be displayed.

INVEST

To evaluate if a user story is well-written, we apply the INVEST criteria:

• Independent: Stories should not depend on each other so they can be implemented and released in any order.
• Negotiable: They capture the essence of a need without dictating specific design decisions (like which database to use).
• Valuable: The feature must deliver actual benefit to the user, not just the developer.
• Estimable: The scope must be clear enough for developers to predict the effort required.
• Small: A story should be small enough that the team can complete it within a single iteration and estimate it with reasonable confidence.
• Testable: It must be verifiable through its acceptance criteria.

Important: The application of the INVEST criteria is often content-dependent. For example, a story that is quite large to implement but cannot be effectively split into separate user stories can still be considered “small enough” while a user story that is objectively faster and easier to implement can be considered “not small” if splitting it up into separate user stories that are still valuable and independent is more elegant. Or a user story that is “independent” in one set of user stories (because all its dependencies have already been implemented) is “not independent” if it is in a set of user stories where its dependencies have not been implemented yet and therefore a dependency is still in the user story set. Understanding this crucial aspect of the INVEST criteria is key to evaluating user stories.

We will now look at these criteria in more detail below.

Independent

An independent story does not overlap with or depend on other stories—it can be scheduled and implemented in any order.

What it is and Why it Matters The “Independent” criterion states that user stories should not overlap in concept and should be schedulable and implementable in any order (Wake 2003). An independent story can be understood, tracked, implemented, and tested on its own, without requiring other stories to be completed first.

This criterion matters for several fundamental reasons:

• Flexible Prioritization: Independent stories allow the business to prioritize the backlog based strictly on value, rather than being constrained by technical dependencies (Wake 2003). Without independence, a high-priority story might be blocked by a low-priority one.
• Accurate Estimation: When stories overlap or depend on each other, their estimates become entangled. For example, if paying by Visa and paying by MasterCard are separate stories, the first one implemented bears the infrastructure cost, making the second one much cheaper (Cohn 2004). This skews estimates.
• Reduced Confusion: By avoiding overlap, independent stories reduce places where descriptions contradict each other and make it easier to verify that all needed functionality has been described (Wake 2003).

How to Evaluate It To determine if a user story is independent, ask:

1. Does this story overlap with another story? If two stories share underlying capabilities (e.g., both involve “sending a message”), they have overlap dependency—the most painful form (Wake 2003).
2. Must this story be implemented before or after another? If so, there is an order dependency. While less harmful than overlap (the business often naturally schedules these correctly), it still constrains planning (Wake 2003).
3. Was this story split along technical boundaries? If one story covers the UI layer and another covers the database layer for the same feature, they are interdependent and neither delivers value alone (Cohn 2004).

How to Improve It If stories violate the Independent criterion, you can improve them using these techniques:

• Combine Interdependent Stories: If two stories are too entangled to estimate separately, merge them into a single story. For example, instead of separate stories for Visa, MasterCard, and American Express payments, combine them: “A company can pay for a job posting with a credit card” (Cohn 2004).
• Partition Along Different Dimensions: If combining makes the story too large, re-split along a different dimension. For overlapping email stories like “Team member sends and receives messages” and “Team member sends and replies to messages”, repartition by action: “Team member sends message”, “Team member receives message”, “Team member replies to message” (Wake 2003).
• Slice Vertically: When stories have been split along technical layers (UI vs. database), re-slice them as vertical “slices of cake” that cut through all layers. Instead of “Job Seeker fills out a resume form” and “Resume data is written to the database”, write “Job Seeker can submit a resume with basic information” (Cohn 2004).

Examples of Stories Violating the Independent Criterion

Example 1: Overlap Dependency

Story A: “As a team member, I want to send and receive messages so that I can communicate with my colleagues.”

• Given I am on the messaging page, When I compose a message and click “Send”, Then the message appears in the recipient’s inbox.
• Given a colleague has sent me a message, When I open my inbox, Then I can read the message.

Story B: “As a team member, I want to reply to messages so that I can indicate which message I am responding to.”

• Given I have received a message, When I click the “Reply” button and submit my response, Then the reply is sent to the original sender.
• Given the reply has been received, When the original sender views the message, Then it is displayed as a reply to the original message.

• Negotiable: Yes. Neither story dictates a specific UI or technology.
• Valuable: Yes. Communication features are clearly valuable to users.
• Estimable: Difficult. Because both stories share the “send” capability, whichever story is implemented second has unpredictable effort—parts of it may already be done, making estimates unreliable.
• Small: Yes. Each story is a manageable chunk of work that fits within a sprint.
• Testable: Yes. Clear acceptance criteria can be written for sending, receiving, and replying.
• Why it violates Independent: Both stories include “sending a message”—this is an overlap dependency, the most harmful form of story dependency (Wake 2003). If Story A is implemented first, parts of Story B are already done. If Story B is implemented first, parts of Story A are already done. This creates confusion about what is covered and makes estimation unreliable.
• How to fix it: Make the dependency explicit (e.g., User story B depends on user story A). Merging them into one story is not an option as it would violate the small criterion, splitting them into three stories (sending, receiving and replying) is not an option as it would still violate the independent criterion and also violate valuable for just sending without receiving. So the best thing we can do is to accept that we cannot always create perfectly independent user stories and instead document this dependency so that when scheduling the implementation of user stories we can directly see that they have to be implemented in a specific order and when estimating user stories we can assume that the functionality in user story A has already been implemented. Hidden dependencies are bad. Full independence is perfect but not always achievable. Explicit dependencies are the pragmatic workaround that addresses the core problem of hidden dependencies while still acknowledging practicality.

Example 2: Technical (Horizontal) Splitting

Story A: “As a job seeker, I want to fill out a resume form so that I can enter my information.”

• Given I am on the resume page, When I fill in my name, address, and education, Then the form displays my entered information.

Story B: “As a job seeker, I want my resume data to be saved so that it is available when I return.”

• Given I have filled out the resume form, When I click “Save”, Then my resume data is available when I log back in.

• Negotiable: Yes. Neither story mandates a specific technology, database, or framework—the implementation details are open to discussion.
• Valuable: No. Neither story delivers value on its own—a form that does not save is useless, and saving data without a form to collect it is equally useless.
• Estimable: Yes. Developers can estimate each technical task.
• Small: Yes. Each is a small piece of work.
• Testable: Yes, though the horizontal split makes end-to-end testing awkward.
• Why it violates Independent: Story B is meaningless without Story A, and Story A is useless without Story B. They are completely interdependent because the feature was split along technical boundaries (UI layer vs. persistence layer) instead of user-facing functionality (Cohn 2004).
• How to fix it: Combine into a single vertical slice: “As a job seeker, I want to submit a resume with basic information (name, address, education) so that employers can find me.” This cuts through all layers and delivers value independently (Cohn 2004).

Quick Check: Consider these two stories for a music streaming app:

• Story A: “As a listener, I want to create playlists so that I can organize my music.”
• Story B: “As a listener, I want to add songs to a playlist so that I can build my collection.”

Are these stories independent? Why or why not?

Reveal Answer

They are not independent — they have an order dependency (the less harmful form, compared to overlap dependency) (Wake 2003). Story B requires playlists to exist (Story A). There are two valid approaches: (1) Combine them: "As a listener, I want to create and populate playlists so that I can organize my music." (2) Accept the dependency: Since order dependencies are less harmful than overlap dependencies, the team can keep both stories separate and simply ensure Story A is scheduled first. The business often naturally handles this ordering correctly (Wake 2003).

Negotiable

A negotiable story captures the essence of a user’s need without locking in specific design or technology decisions—the details are worked out collaboratively.

What it is and Why it Matters The “Negotiable” criterion states that a user story is not an explicit contract for features; rather, it captures the essence of a user’s need, leaving the details to be co-created by the customer and the development team during development (Wake 2003). A good story captures the essence, not the details (see also “Requirements Vs. Design”).

This criterion matters for several fundamental reasons:

• Enabling Collaboration: Because stories are intentionally incomplete, the team is forced to have conversations to fill in the details. Ron Jeffries describes this through the three C’s: Card (the story text), Conversation (the discussion), and Confirmation (the acceptance tests) (Cohn 2004). The card is merely a token promising a future conversation (Wake 2003).
• Evolutionary Design: High-level stories define capabilities without over-constraining the implementation approach (Wake 2003). This leaves room to evolve the solution from a basic form to an advanced form as the team learns more about the system’s needs.
• Avoiding False Precision: Including too many details early creates a dangerous illusion of precision (Cohn 2004). It misleads readers into believing the requirement is finalized, which discourages necessary conversations and adaptation.

How to Evaluate It To determine if a user story is negotiable, ask:

1. Does this story dictate a specific technology or design decision? Words like “MongoDB”, “HTTPS”, “REST API”, or “dropdown menu” in a story are red flags that it has left the space of requirements and entered the space of design.
2. Could the development team solve this problem using a completely different technology or layout, and would the user still be happy? If the answer is yes, the story is negotiable. If the answer is no, the story is over-constrained.
3. Does the story include UI details? Embedding user interface specifics (e.g., “a print dialog with a printer list”) introduces premature assumptions before the team fully understands the business goals (Cohn 2004).

How to Improve It If a story violates the Negotiable criterion, you can improve it using these techniques:

• Focus on the “Why”: Use “So that” clauses to clarify the underlying goal, which allows the team to negotiate the “How”.
• Specify What, Not How: Replace technology-specific language with the user need it serves. Instead of “use HTTPS”, write “keep data I send and receive confidential”.
• Define Acceptance Criteria, Not Steps: Define the outcomes that must be true, rather than the specific UI clicks or database queries required.
• Keep the UI Out as Long as Possible: Avoid embedding interface details into stories early in the project (Cohn 2004). Focus on what the user needs to accomplish, not the specific controls they will use.

Examples of Stories Violating the Negotiable Criterion

Example 1: The Technology-Specific Story

“As a subscriber, I want my profile settings saved in a MongoDB database so that they load quickly the next time I log in.”

• Given I am logged in and I change my profile settings, When I log out and log back in, Then my profile settings are still applied.

• Independent: Yes. Saving profile settings does not depend on other stories.
• Valuable: Yes. Remembering user settings is clearly valuable.
• Estimable: Yes. A developer can estimate the effort to implement settings persistence.
• Small: Yes. This is a focused piece of work.
• Testable: Yes. You can verify that settings persist across sessions.
• Why it violates Negotiable: Specifying “MongoDB” is a design decision. The user does not care where the data lives. The engineering team might realize that a relational SQL database or local browser caching is a much better fit for the application’s architecture.
• How to fix it: “As a subscriber, I want the system to remember my profile settings so that I don’t have to re-enter them every time I log in.”

Example 2: The UI-Specific Story

“As a student, I want to select my courses from a dropdown menu so that I can register for the upcoming semester.”

• Given I am on the registration page, When I select a course from the dropdown menu and click “Register”, Then the course is added to my schedule.

• Independent: Yes. Course registration does not depend on other stories.
• Valuable: Yes. Registering for courses is clearly valuable to the student.
• Estimable: Yes. Building a course selection feature is well-understood work.
• Small: Yes. This is a single, focused feature.
• Testable: Yes. You can verify that selecting a course adds it to the schedule.
• Why it violates Negotiable: “Dropdown menu” is a specific UI design decision. The user’s actual need is to select courses, which could be achieved through many different interfaces—a search bar, a visual schedule builder, a drag-and-drop interface, or even a conversational assistant. By prescribing the dropdown, the story constrains the design team before they have explored the problem space (Cohn 2004).
• How to fix it: “As a student, I want to select courses for the upcoming semester so that I can register for my classes.” Similarly, specifying protocols (e.g., “use HTTPS”), frameworks (e.g., “built with React”), or architectural patterns (e.g., “using microservices”) are all design decisions that constrain the solution space.

Quick Check: “As a restaurant owner, I want customers to scan a QR code at their table to view the menu on their phone so that I don’t have to print physical menus.”

Does this story satisfy the Negotiable criterion?

Reveal Answer

No. "Scan a QR code" prescribes a specific solution. The owner's actual need is for customers to access the menu without physical copies — this could be achieved via QR codes, NFC tags, a URL, a dedicated app, or a table-mounted tablet. A negotiable version: "As a restaurant owner, I want customers to access the menu digitally at their table so that I can eliminate printed menus."

What to do when the user really needs the specific technology?

Sometimes the required solution does indeed have to conform to the specific technology that the customer is using in their organization. In software engineering we call this a “technical constraint”. In these cases user stories are usually not the ideal format to specify these requirement in, since these technical constraints are often cross-cutting and should be included in the design of many different independent features. User stories are a mechanism to document requirements that primarily concern the functionality of the software. Other kinds of requirements, especially those that can’t be declared “done” should use different kinds of requirements specifications.

Valuable

A valuable story delivers tangible benefit to the customer, purchaser, or user—not just to the development team.

What it is and Why it Matters The “Valuable” criterion states that every user story must deliver tangible value to the customer, purchaser, or user—not just to the development team (Wake 2003). A good story focuses on the external impact of the software in the real world: if we frame stories so their impact is clear, product owners and users can understand what the stories bring and make good prioritization choices (Wake 2003).

This criterion matters for several fundamental reasons:

• Informed Prioritization: The product owner prioritizes the backlog by weighing each story’s value against its cost. If a story’s business value is opaque—because it is written in technical jargon—the customer cannot make intelligent scheduling decisions (Cohn 2004).
• Avoiding Waste: Stories that serve only the development team (e.g., refactoring for its own sake, adopting a trendy technology) consume iteration capacity without moving the product closer to its users’ goals. The IRACIS framework provides a useful lens for value: does the story Increase Revenue, Avoid Costs, or Improve Service? (Wake 2003)
• User vs. Purchaser Value: It is tempting to say every story must be valued by end-users, but that is not always correct. In enterprise environments, the purchaser may value stories that end-users do not care about (e.g., “All configuration is read from a central location” matters to the IT department managing 5,000 machines, not to daily users) (Cohn 2004).

How to Evaluate It To determine if a user story is valuable, ask:

1. Would the customer or user care if this story were dropped? If only developers would notice, the story likely lacks user-facing value.
2. Can the customer prioritize this story against others? If the story is written in “techno-speak” (e.g., “All connections go through a connection pool”), the customer cannot weigh its importance (Cohn 2004).
3. Does this story describe an external effect or an internal implementation detail? Valuable stories describe what happens on the edge of the system—the effects of the software in the world—not how the system is built internally (Wake 2003).

How to Improve It If stories violate the Valuable criterion, you can improve them using these techniques:

• Rewrite for External Impact: Translate the technical requirement into a statement of benefit for the user. Instead of “All connections to the database are through a connection pool”, write “Up to fifty users should be able to use the application with a five-user database license” (Cohn 2004).
• Let the Customer Write: The most effective way to ensure a story is valuable is to have the customer write it in the language of the business, rather than in technical jargon (Cohn 2004).
• Focus on the “So That”: A well-written “so that” clause forces the author to articulate the real-world benefit. If you cannot complete “so that [some user benefit]” without referencing technology, the story is likely not valuable.
• Complete the Acceptance Criteria: A story may appear valuable but have incomplete acceptance criteria that leave out essential functionality, effectively making the delivered feature useless.

Examples of Stories Violating the Valuable Criterion

Example 1: Incomplete Acceptance Criteria That Miss the Value

“As a travel agent, I want to search for available flights for a client’s trip so that I can find the best option for them.”

• Given the travel agent enters a departure city, destination city, and travel date, When they click “Search”, Then a list of available flights for that route is displayed.
• Given the search results are displayed, When the travel agent selects a flight from the list, Then the booking page for that flight is shown.

• Independent: Yes. Searching for flights does not depend on other stories.
• Negotiable: Yes. The story does not prescribe any specific technology, UI layout, or data source—the team is free to decide how to build the search.
• Estimable: Yes. Building a flight search with results display is well-understood work with clear scope.
• Small: Yes. A single search-and-display feature fits within a sprint.
• Testable: Yes. The given acceptance criteria can be translated into an unambiguous test with concrete steps and clear testing criteria.
• Why it violates Valuable: The story text promises real value (“find the best option”), but the acceptance criteria do not mention it. Since acceptance criteria define the scope of an acceptance implementation to the user story, these acceptance criteria accept user stories that do not implement the main functionality. A list of flight names and times is useless to a travel agent who needs to compare prices, layover durations, and total travel time to recommend the best option to a client. Without this comparison data, the agent cannot accomplish the goal stated in the “so that” clause. The feature technically works—flights are displayed and can be selected—but it does not solve the user’s actual problem. This illustrates why acceptance criteria must capture the essential functionality that delivers the value promised by the story. A story may appear valuable based on its text, but if its acceptance criteria leave out the information or capability that makes the feature genuinely useful, the delivered feature might not provide real value to the user. In this example, the acceptance criteria should help the developers understand what information is needed for the user to find the best option. Since the developers could pick any random subset of attributes their selection might not be what the user really needs to see. So our acceptance criteria should clearly communicate what it is the user really needs.
• How to fix it: Add acceptance criteria that capture the comparison capability essential to the agent’s real goal: “Given the search results are displayed, When the travel agent views the list, Then each flight shows the ticket price, number of stops, layover durations, and total travel time so the agent can compare options side by side.”

Quick Check: “As a backend developer, I want to migrate our logging from printf statements to a structured logging framework so that log entries are in JSON format.”

Does this story satisfy the Valuable criterion?

Reveal Answer

No. While this story might make it easier for developers to deliver more value to the user in the future due to better maintainability, it does not directly deliver value to a user of the system. We consider a user story valuable only if it meets the need of a user.

Example 2: The Developer-Centric Story

“As a developer, I want to refactor the authentication module so that the codebase is easier to maintain.”

• Given the authentication module has been refactored, When a developer deploys the updated module, Then all existing authentication endpoints return identical responses.

• Independent: Yes. Refactoring the auth module does not depend on other stories.
• Negotiable: Yes. The story does not dictate a specific technology, language, or design decision—the team is free to choose how to improve maintainability.
• Estimable: Yes. A developer can estimate the effort of a refactoring task.
• Small: Yes. Refactoring a single module can fit within a sprint.
• Testable: Yes. You can verify the refactored module passes all existing authentication tests.
• Why it violates Valuable: The story is written entirely from the developer’s perspective. The user does not care about internal code quality. The “so that” clause (“the codebase is easier to maintain”) describes a developer benefit, not a user benefit (Cohn 2004). A product owner cannot weigh “easier to maintain” against user-facing features.
• How to fix it: If there is a legitimate user-facing reason (e.g., performance), rewrite the story around that benefit: “As a registered member, I want to log in without noticeable delay so that I can start using the application immediately.”

Estimable

An estimable story has a scope clear enough for the development team to make a reasonable judgment about the effort required.

What it is and Why it Matters The “Estimable” criterion states that the development team must be able to make a reasonable judgment about a story’s size, cost, or time to deliver (Wake 2003). While precision is not the goal, the estimate must be useful enough for the product owner to prioritize the story against other work (Cohn 2004).

This criterion matters for several fundamental reasons:

• Enabling Prioritization: The product owner ranks stories by comparing value to cost. If a story cannot be estimated, the cost side of this equation is unknown, making informed prioritization impossible (Cohn 2004).
• Supporting Planning: Stories that cannot be estimated cannot be reliably scheduled into an iteration. Without sizing information, the team risks committing to more (or less) work than they can deliver.
• Surfacing Unknowns Early: An unestimable story is a signal that something important is not understood—either the domain, the technology, or the scope. Recognizing this early prevents costly surprises later.

How to Evaluate It Developers generally cannot estimate a story for one of three reasons (Cohn 2004):

1. Lack of Domain Knowledge: The developers do not understand the business context. For example, a story saying “New users are given a diabetic screening” could mean a simple web questionnaire or an at-home physical testing kit—without clarification, no estimate is possible (Cohn 2004).
2. Lack of Technical Knowledge: The team understands the requirement but has never worked with the required technology. For example, a team asked to expose a gRPC API when no one has experience with Protocol Buffers or gRPC cannot estimate the work (Cohn 2004).
3. The Story is Too Big: An epic like “A job seeker can find a job” encompasses so many sub-tasks and unknowns that it cannot be meaningfully sized as a single unit (Cohn 2004).

How to Improve It The approach to fixing an unestimable story depends on which barrier is blocking estimation:

• Conversation (for Domain Knowledge Gaps): Have the developers discuss the story directly with the customer. A brief conversation often reveals that the requirement is simpler (or more complex) than assumed, making estimation possible (Cohn 2004).
• Spike (for Technical Knowledge Gaps): Split the story into two: an investigative spike—a brief, time-boxed experiment to learn about the unknown technology—and the actual implementation story. The spike itself is always given a defined maximum time (e.g., “Spend exactly two days investigating credit card processing”), which makes it estimable. Once the spike is complete, the team has enough knowledge to estimate the real story (Cohn 2004).
• Disaggregate (for Stories That Are Too Big): Break the epic into smaller, constituent stories. Each smaller piece isolates a specific slice of functionality, reducing the cognitive load and making estimation tractable (Cohn 2004).

Examples of Stories Violating the Estimable Criterion

Example 1: The Unknown Domain

“As a patient, I want to receive a personalized wellness screening so that I can understand my health risks.”

• Given I am a new patient registering on the platform, When I complete the wellness screening, Then I receive a personalized health risk summary based on my answers.

• Independent: Yes. The screening feature does not depend on other stories.
• Negotiable: Yes. The specific questions and screening logic are open to discussion.
• Valuable: Yes. Personalized health screening is clearly valuable to patients.
• Small: Yes. A single screening workflow can fit within a sprint—once the scope is clarified.
• Testable: Yes. Acceptance criteria can define specific screening outcomes for specific patient profiles.
• Why it violates Estimable: The developers do not know what “personalized wellness screening” means in this context. It could be a simple 5-question web form or a complex algorithm that integrates with lab data. Without domain knowledge, the team cannot estimate the effort (Cohn 2004).
• How to fix it: Have the developers sit down with the customer (e.g., a qualified nurse or medical expert) to clarify the scope. Once the team learns it is a simple web questionnaire, they can estimate it confidently.

Example 2: The Unknown Technology

“As an enterprise customer, I want to access the system’s data through a gRPC API so that I can integrate it with my existing microservices infrastructure.”

• Given an enterprise client sends a gRPC request for user data, When the system processes the request, Then the system returns the requested data in the correct Protobuf-defined format.

• Independent: Yes. Adding an integration interface does not depend on other stories.
• Negotiable: Partially. The customer has specified gRPC, which is normally a technology choice that would violate Negotiable. However, in this case the customer’s existing microservices infrastructure genuinely requires gRPC compatibility, making it a hard constraint rather than an arbitrary design decision. The service contract and data schema remain open to discussion.

Note: Not all technology specifications violate Negotiable. When the customer’s existing infrastructure genuinely requires a specific protocol or format, that constraint is a hard requirement, not an arbitrary design choice. The key question is: could the user’s goal be met equally well with a different technology? If a gRPC customer cannot use REST, then gRPC is a requirement, not a design decision (Cohn 2004).

• Valuable: Yes. Enterprise integration is clearly valuable to the purchasing organization.
• Small: Yes. A single service endpoint can fit within a sprint—once the team understands the technology.
• Testable: Yes. You can verify the interface returns the correct data in the correct format.
• Why it violates Estimable: No one on the development team has ever built a gRPC service or worked with Protocol Buffers. They understand what the customer wants but have no experience with the technology required to deliver it, making any estimate unreliable (Cohn 2004).
• How to fix it: Split into two stories: (1) a time-boxed spike—”Investigate gRPC integration: spend at most two days building a proof-of-concept service”—and (2) the actual implementation story. After the spike, the team has enough knowledge to estimate the real work (Cohn 2004).

Quick Check: “As a content creator, I want the platform to automatically generate accurate subtitles for my uploaded videos so that my content is accessible to hearing-impaired viewers.”

The development team has never worked with speech-to-text technology. Is this story estimable?

Reveal Answer

No. The team lacks the technical knowledge required to estimate the effort — this is the "unknown technology" barrier. The fix: split into a time-boxed spike ("Spend two days evaluating speech-to-text APIs and building a proof-of-concept") and the actual implementation story. After the spike, the team will have enough experience to estimate the real work.

Small

A small story is a manageable chunk of work that can be completed within a single iteration—not so large it becomes an epic, not so small it loses meaningful context. A user story should be as small as it can be while still delivering value.

What it is and Why it Matters The “Small” criterion states that a user story should be appropriately sized so that it can be comfortably completed by the development team within a single iteration (Cohn 2004). Stories typically represent at most a few person-weeks of work; some teams restrict them to a few person-days (Wake 2003). If a story is too large, it is called an epic and must be broken down. If a story is too small, it should be combined with related stories.

This criterion matters for several fundamental reasons:

• Predictability: Large stories are notoriously difficult to estimate accurately. The smaller the story, the higher the confidence the team has in their estimate of the effort required (Cohn 2004).
• Risk Reduction: If a massive story spans an entire sprint (or spills over into multiple sprints), the team risks delivering zero value if they hit a roadblock. Smaller stories ensure a steady, continuous flow of delivered value.
• Faster Feedback: Smaller stories reach a “Done” state faster, meaning they can be tested, reviewed by the product owner, and put in front of users much sooner to gather valuable feedback.

How to Evaluate It To determine if a user story is appropriately sized, ask:

1. Is it a compound story? Words like and, or, and but in the story description (e.g., “I want to register and manage my profile and upload photos”) often indicate that multiple stories are hiding inside one. A compound story is an “epic” that aggregates multiple easily identifiable shorter stories (Cohn 2004).
2. Can it be split while still being valuable? If a user story can be split into separate stories that are still valuable then this is often a good idea. If the smaller parts do not individually satisfy valuable, we still consider the larger user story “small”.
3. Is it a complex, uncertain story? If the story is large because of inherent uncertainty (new technology, novel algorithm), it is a complex story and should be split into a spike and an implementation story (Cohn 2004).

How to Improve It The approach to fixing a story that violates the Small criterion depends on whether it is too big or too small:

Stories that are too big:

• Split by Workflow Steps (CRUD): Instead of “As a job seeker, I want to manage my resume”, split along operations: create, edit, delete, and manage multiple resumes (Cohn 2004).
• Split by Data Boundaries: Instead of splitting by operation, split by the data involved: “add/edit education”, “add/edit job history”, “add/edit salary” (Cohn 2004).
• Slice the Cake (Vertical Slicing): Never split along technical boundaries (one story for UI, one for database). Instead, split into thin end-to-end “vertical slices” where each story touches every architectural layer and delivers complete, albeit narrow, functionality (Cohn 2004).
• Split by Happy/Sad Paths: Build the “happy path” (successful transaction) as one story, and handle the error states (declined cards, expired sessions) in subsequent stories.

Examples of Stories Violating the Small Criterion

Example 1: The Epic (Too Big)

“As a traveler, I want to plan a vacation so that I can book all the arrangements I need in one place.”

• Given I have selected travel dates and a destination, When I search for vacation packages, Then I see available flights, hotels, and rental cars with pricing.
• Given I have selected a flight, hotel, and rental car, When I click “Book”, Then all reservations are confirmed and I receive a booking confirmation email.

• Independent: Yes. Planning a vacation does not overlap with other stories.
• Negotiable: Yes. The specific features and UI are open to discussion.
• Valuable: Yes. End-to-end vacation planning is clearly valuable to travelers.
• Estimable: Partially. A developer can give a rough order-of-magnitude estimate (“several months”), but the hidden complexity within this epic makes the estimate too unreliable for sprint planning. Violations of Small often cause violations of Estimable, since epics contain hidden complexity (Cohn 2004).
• Testable: Yes. Acceptance criteria can be written, though they would need to be much more detailed once the epic is broken into smaller stories.
• Why it violates Small: “Planning a vacation” involves searching for flights, comparing hotels, booking rental cars, managing an itinerary, handling payments, and much more. This is an epic containing many stories. It cannot be completed in a single sprint (Cohn 2004).
• How to fix it: Disaggregate into smaller vertical slices: “As a traveler, I want to search for flights by date and destination so that I can find available options”, “As a traveler, I want to compare hotel prices for my destination so that I can choose one within my budget”, etc.

Example 2: The Micro-Story (Too Small)

“As a job seeker, I want to edit the date for each community service entry on my resume so that I can correct mistakes.”

• Given I am viewing a community service entry on my resume, When I change the date field and click “Save”, Then the updated date is displayed on my resume.

• Independent: Yes. Editing a single date field does not depend on other stories.
• Negotiable: Yes. The exact editing interaction is open to discussion.
• Valuable: Yes. Correcting resume data is valuable to the user.
• Estimable: Yes. Editing a single field is trivially estimable.
• Testable: Yes. Clear pass/fail criteria can be written.
• Why it violates Small: This story is too small. The administrative overhead of writing, estimating, and tracking this story card takes longer than actually implementing the change. Having dozens of stories at this granularity buries the team in disconnected details—what Wake calls a “bag of leaves” (Wake 2003).
• How to fix it: Combine with related micro-stories into a single meaningful story: “As a job seeker, I want to edit all fields of my community service entries so that I can keep my resume accurate.” (Cohn 2004)

Quick Check: “As a job seeker, I want to manage my resume so that employers can find me.”

Is this story appropriately sized?

Reveal Answer

No — it is too big (an epic). "Manage my resume" hides multiple stories: create a resume, edit sections, upload a photo, delete a resume, manage multiple versions. The word "manage" is often a signal that a story is a compound epic. Split by CRUD operations: "I want to create a resume", "I want to edit my resume", "I want to delete my resume" — or by data boundaries: "I want to add/edit my education", "I want to add/edit my work history", "I want to add/edit my skills".

Testable

A testable story has clear, objective, and measurable acceptance criteria that allow the team to verify definitively when the work is done.

What it is and Why it Matters The “Testable” criterion dictates that a user story must have clear, objective, and measurable conditions that allow the team to verify when the work is officially complete. If a story is not testable, it can never truly be considered “Done”.

This criterion matters for several crucial reasons:

• Shared Understanding: It forces the product owner and the development team to align on the exact expectations. It removes ambiguity and prevents the dreaded “that’s not what I meant” conversation at the end of a sprint.
• Proving Value: A user story represents a slice of business value. If you cannot test the story, you cannot prove that it successfully delivers that value to the user.
• Enabling Quality Assurance: Testable stories allow QA engineers (and developers practicing Test-Driven Development) to write their test cases—whether manual or automated—before a single line of production code is written.

How to Evaluate It To determine if a user story is testable, ask yourself the following questions:

1. Can I write a definitive pass/fail test for this? If the answer relies on someone’s opinion or mood, it is not testable.
2. Does the story contain “weasel words”? Look out for subjective adjectives and adverbs like fast, easy, intuitive, beautiful, modern, user-friendly, robust, or seamless. These words are red flags that the story lacks objective boundaries.
3. Are the Acceptance Criteria clear? Does the story have defined boundaries that outline specific scenarios and edge cases?

How to Improve It If you find a story that violates the Testable criterion, you can improve it by replacing subjective language with quantifiable metrics and concrete scenarios:

• Quantify Adjectives: Replace subjective terms with hard numbers. Change “loads fast” to “loads in under 2 seconds”. Change “supports a lot of users” to “supports 10,000 concurrent users”.
• Use the Given/When/Then Format: Borrow from Behavior-Driven Development (BDD) to write clear acceptance criteria. Establish the starting state (Given), the action taken (When), and the expected, observable outcome (Then).
• Define “Intuitive” or “Easy”: If the goal is a “user-friendly” interface, make it testable by tying it to a metric, such as: “A new user can complete the checkout process in fewer than 3 clicks without relying on a help menu.”

Examples of Stories Violating the Testable Criterion

Below are two user stories that are not testable but still satisfy (most) other INVEST criteria.

Example 1: The Subjective UI Requirement

“As a marketing manager, I want the new campaign landing page to feature a gorgeous and modern design, so that it appeals to our younger demographic.”

• Given the landing page is deployed, When a visitor from the 18-24 demographic views it, Then the design looks gorgeous and modern.

• Independent: Yes. It doesn’t inherently rely on other features being built first.
• Negotiable: Yes. The exact layout and tech used to build it are open to discussion.
• Valuable: Yes. A landing page to attract a younger demographic provides clear business value.
• Estimable: Yes. Generally, a frontend developer can estimate the effort to build a standard landing page independent of what specific definition of “gorgeous and modern” is used.
• Small: Yes. Building a single landing page easily fits within a single sprint.
• Why it violates Testable: “Gorgeous”, “modern”, and “appeals to” are completely subjective. What one developer thinks is modern, the marketing manager might think is ugly.
• How to fix it: Tie it to a specific, measurable design system or user-testing metric. (e.g., “Acceptance Criteria: The design strictly adheres to the new V2 Brand Guidelines and passes a 5-second usability test with a 4/5 rating from a focus group of 18-24 year olds.”)

Example 2: The Vague Performance Requirement

“As a data analyst, I want the monthly sales report to generate instantly, so that my workflow isn’t interrupted by loading screens.”

• Given the database contains 5 years of sales data, When the analyst requests the monthly sales report, Then the report generates instantly.

• Independent: Yes. Optimizing or building this report can be done independently.
• Negotiable: Yes. The team can negotiate how to achieve the speed (e.g., caching, database indexing, background processing).
• Valuable: Yes. Saving the analyst’s time is a clear operational benefit.
• Estimable: Yes. A developer can estimate the effort for standard report optimizations (query tuning, caching, indexing, pagination) regardless of the specific latency threshold that will ultimately be defined. The implementation work is predictable even though the acceptance threshold is not—just as in Example 1 above, where the effort to build a landing page does not depend on the specific definition of “modern”.
• Small: Yes. It is a focused optimization on a single report.
• Why it violates Testable: “Instantly” is subjective. Does it mean 100 milliseconds? Two seconds? Zero perceived delay? Without a quantifiable threshold, QA cannot write a definitive pass/fail test—and the developer cannot know when to stop optimizing.
• How to fix it: Replace the subjective word with a quantifiable service level indicator. (e.g., “Acceptance Criteria: Given the database contains 5 years of sales data, when the analyst requests the monthly sales report, then the data renders on screen in under 2.5 seconds at the 95th percentile.”)

Example 3: The Subjective Audio Requirement

“As a podcast listener, I want the app’s default intro chime to play at a pleasant volume, so that it doesn’t startle me when I open the app.”

• Given I open the app for the first time, When the intro chime plays, Then the volume is at a pleasant level.

• Independent: Yes. Adjusting the audio volume doesn’t rely on other features.
• Negotiable: Yes. The exact decibel level or method of adjustment is open to discussion.
• Valuable: Yes. Improving user comfort directly enhances the user experience.
• Estimable: Yes. Changing a default audio volume variable or asset is a trivial, highly predictable task (e.g., a 1-point story). The developers know exactly how much effort is involved.
• Small: Yes. It will take a few minutes to implement.
• Why it violates Testable: “Pleasant volume” is entirely subjective. A volume that is pleasant in a quiet library will be inaudible on a noisy subway. Because there is no objective baseline, QA cannot definitively pass or fail the test.
• How to fix it: “Acceptance Criteria: The default intro chime must be normalized to -16 LUFS (Loudness Units relative to Full Scale).”

How INVEST supports agile processes like Scrum

The INVEST principles matter because they act as a compass for creating high-quality, actionable user stories that align with Agile goals and principles of processes like Scrum. By ensuring stories are Independent and Small, teams gain the scheduling flexibility needed to implement and release features in any order within short iterations. If user stories are not independent, it becomes hard to always select the highest value user stories. If they are not small, it becomes hard to select a Sprint Backlog that fits the team’s velocity.
Negotiable stories promote essential dialog between developers and stakeholders, while Valuable ones ensure that every effort translates into a meaningful benefit for the user. Finally, stories that are Estimable and Testable provide the clarity required for accurate sprint planning and objective verification of the finished product. In Scrum and XP, user stories are estimated during the Planning activity.

FAQ on INVEST

How are Estimable and Testable different?

Estimable refers to the ability of developers to predict the size, cost, or time required to deliver a story. This attribute relies on the story being understood well enough and having a clear enough scope to put useful bounds on those guesses.

Testable means that a story can be verified through objective acceptance criteria. A story is considered testable if there is a definitive “Yes” or “No” answer to whether its objectives have been achieved.

In practice, these two are closely linked: if a story is not testable because it uses vague terms like “fast” or “high accuracy”, it becomes nearly impossible to estimate the actual effort needed to satisfy it. But that is not always the case.

Here are examples of user stories that isolate those specific violations of the INVEST criteria:

Violates Testable but not Estimable User Story: “As a site administrator, I want the dashboard to feel snappy when I log in so that I don’t get frustrated with the interface.”

• Why it violates Testable: Terms like “snappy” or “fast” are subjective. Without a specific metric (e.g., “loads in under 2 seconds”), there is no objective “Yes” or “No” answer to determine if the story is done.
• Why it is still Estimable: The developers know the dashboard and its tech stack well. Regardless of how “snappy” is ultimately defined, they can estimate the effort for standard front-end optimizations (lazy loading, caching, query tuning) that would improve perceived responsiveness. The implementation work is predictable even though the acceptance threshold is not, because for all reasonable interpretations of snappy, the implementation effort is roughly the same, as these techniques are well understood and often available in libraries. Note: Depending on your personal experience with web development, you might evaluate this example as not estimable. That would also be a valid judgment. In that case, check out the Subjective UI Requirement Example above for another example.

Violates Estimable but not Testable User Story: “As a safety officer, I want the system to automatically identify every pedestrian in this complex, low-light video feed so that I can monitor crosswalk safety without reviewing hours of footage manually.”

• Why it violates Estimable: This is a “research project”. Because the technical implementation is unknown or highly innovative, developers cannot put useful bounds on the time or cost required to solve it.
• Why it is still Testable: It is perfectly testable; you could poll 1,000 humans to verify if the software’s identifications match reality. The outcome is clear, but the effort to reach it is not.
• What about Small? This user story also violates Small—it is a very large feature that would span multiple sprints. However, the key insight is that even if we broke it into smaller pieces, each piece would still be unestimable due to the technical uncertainty. The Estimable violation is the root cause here, not the size.

How are Estimable and Small different?

While they are related, Estimable and Small focus on different dimensions of a user story’s readiness for development.

Estimable: Predictability of Effort

Estimable refers to the developers’ ability to provide a reasonable judgment regarding the size, cost, or time required to deliver a story.

• Requirements: For a story to be estimable, it must be understood well enough and be stable enough that developers can put “useful bounds” on their guesses.
• Barriers: A story may fail this criterion if developers lack domain knowledge, technical knowledge (requiring a “technical spike” to learn), or if the story is so large (an epic) that its complexity is hidden.
• Goal: It ensures the Product Owner can prioritize stories by weighing their value against their cost.

Small: Manageability of Scope

Small refers to the physical magnitude of the work. A story should be a manageable chunk that can be completed within a single iteration or sprint.

• Ideal Size: Most teams prefer stories that represent between half a day and two weeks of work.
• Splitting: If a story is too big, it should be split into smaller, still-valuable “vertical slices” of functionality. However, a story shouldn’t be so small (like a “bag of leaves”) that it loses its meaningful context or value to the user.
• Goal: Smaller stories provide more scheduling flexibility and help maintain momentum through continuous delivery.

Key Differences

1. Nature of the Constraint: Small is a constraint on volume, while Estimable is a constraint on clarity.
2. Accuracy vs. Size: While smaller stories tend to get more accurate estimates, a story can be small but still unestimable. For example, a “Research Project” or investigative spike might involve a very small amount of work (reading one document), but because the outcome is unknown, it remains impossible to estimate the time required to actually solve the problem.
3. Predictability vs. Flow: Estimability is necessary for planning (knowing what fits in a release), while Smallness is necessary for flow (ensuring work moves through the system without bottlenecks).

Is there often a tradeoff between Small and Valuable?

Yes! When writing user stories this is one of the most common trade-offs to consider. The more valuable a user story is, the larger it becomes. When considering this trade-off the best advice would be to think of valuable as a binary dimension. Once a user story adds some reasonable value to the user, we consider it valuable. So aiming to write the smallest user stories that are still valuable is often a good approach. Optimizing for small until the user story becomes not valuable anymore. A user story can become too small when writing and estimating it takes more time than implementing it. Then it should be combined with other user stories even if the smaller user story is still somewhat valuable. Whether a user story is “good” or “bad” is not a binary criterion, but a spectrum. Aiming to reasonably improve user stories is a desirable goal, but in a practical setting, “good enough” is often sufficient while “perfect” can be a waste of time.

Is INVEST evaluated primarily on the main body of the user story or the acceptance criteria?

Since acceptance critiera define the actual scope of what defines a correct implementation of the requirement, they are the decision driver for INVEST. The main body can be seen as a gentle summary. But for INVEST the acceptance criteria usually “overrule” the main body of the user story.

Common mistakes in user stories

Acceptance criteria omit an essential step, yet the story is claimed to be “Valuable” E.g., a user story about blocking a user whose acceptance criteria include “given I have blocked a user” but never specify how the user actually performs the block.

Dependent stories are claimed to be “Independent” E.g., a story for creating a post and a story for liking a post are marked independent, even though liking requires a post to exist. E.g., a story for logging in and a story for creating or liking a post are marked independent, even though the latter presupposes authentication.

”So that…” is circular or merely restates the feature E.g., “As a user, I want to like/unlike a post on my feed so that I can engage and interact with the content.” Engage is just a synonym for like/unlike, and content is just a synonym for post — the rationale explains nothing. A good “so that” states the underlying motivation: e.g., “so that I can signal approval to the author.”

Acceptance criteria are missing the key assertion E.g., “Given I am on the login screen, when I enter the correct email and password and click Login, then I should be redirected to the home screen.” Being redirected to the home screen does not confirm a successful login. The criterion should also assert that the user is authenticated — for example, that their name appears in the header or that they can access protected content.

Applicability

User stories are ideal for iterative, customer-centric projects where requirements might change frequently.

Limitations

User stories can struggle to capture non-functional requirements like performance, security, or reliability, and they are generally considered insufficient for safety-critical systems like spacecraft or medical devices.

Practice

Acknowledgements

Thanks to Allison Gao for constructive suggestions on how to improve this chapter.

Overview

In software engineering, a design pattern is a common, acceptable solution to a recurring design problem that arises within a specific context. The concept did not originate in computer science, but rather in architecture. Christopher Alexander, an architect who pioneered the idea of pattern languages, defined a pattern beautifully (A Pattern Language, 1977): “Each pattern describes a problem which occurs over and over again in our environment, and then describes the core of the solution to that problem, in such a way that you can use this solution a million times over, without ever doing it the same way twice”.

In software development, design patterns refer to medium-level abstractions that describe structural and behavioral aspects of software. They sit between low-level language idioms (like how to efficiently concatenate strings in Java) and large-scale architectural patterns (like Model-View-Controller or client-server patterns). Structurally, they deal with classes, objects, and the assignment of responsibilities; behaviorally, they govern method calls, message sequences, and execution semantics.

Anatomy of a Pattern

A true pattern is more than simply a good idea or a random solution; it requires a structured format to capture the problem, the context, the solution, and the consequences. While various authors use slightly different templates, the fundamental anatomy of a design pattern contains the following essential elements:

• Pattern Name: A good name is vital as it becomes a handle we can use to describe a design problem, its solution, and its consequences in a word or two. Naming a pattern increases our design vocabulary, allowing us to design and communicate at a higher level of abstraction.
• Context: This defines the recurring situation or environment in which the pattern applies and where the problem exists.
• Problem: This describes the specific design issue or goal you are trying to achieve, along with the constraints symptomatic of an inflexible design.
• Forces: This outlines the trade-offs and competing concerns that must be balanced by the solution.
• Solution: This describes the elements that make up the design, their relationships, responsibilities, and collaborations. It specifies the spatial configuration and behavioral dynamics of the participating classes and objects.
• Consequences: This explicitly lists the results, costs, and benefits of applying the pattern, including its impact on system flexibility, extensibility, portability, performance, and other quality attributes.

GoF Design Patterns

The GoF (Gang of Four) design patterns are organized into three categories based on the type of design problem they address:

The full GoF catalog contains 23 patterns (5 creational, 7 structural, 11 behavioral). The lists below cover the subset we treat in detail in this chapter; the remaining GoF patterns (Prototype; Bridge, Decorator, Flyweight, Proxy; Chain of Responsibility, Interpreter, Iterator, Memento, Template Method) are equally important and worth studying from the original catalog.

Creational Patterns address the problem of object creation—how to instantiate objects in a flexible, decoupled way:

• Factory Method: Defines an interface for creating an object but lets subclasses decide which class to instantiate, deferring creation to subclasses.
• Abstract Factory: Provides an interface for creating families of related objects without specifying their concrete classes.
• Builder: Separates step-by-step construction of a complex object from the representation being built.
• Singleton: Ensures a class has only one instance while providing a controlled global point of access to it.

Structural Patterns address the problem of class and object composition—how to assemble objects and classes into larger structures:

• Adapter: Converts the interface of a class into another interface clients expect, letting classes work together that otherwise couldn’t due to incompatible interfaces.
• Composite: Composes objects into tree structures to represent part-whole hierarchies, letting clients treat individual objects and compositions uniformly.
• Façade: Provides a unified interface to a set of interfaces in a subsystem, making the subsystem easier to use.

Behavioral Patterns address the problem of object interaction and responsibility—how objects communicate and distribute work:

• Strategy: Defines a family of algorithms, encapsulates each one, and makes them interchangeable at runtime, letting the algorithm vary independently from clients that use it.
• Observer: Establishes a one-to-many dependency between objects, ensuring that dependent objects are automatically notified and updated whenever the subject’s state changes.
• Command: Encapsulates a request as an object, allowing invokers to be configured with different actions and supporting undo, queuing, logging, and macro commands.
• State: Encapsulates state-based behavior into distinct classes, allowing a context object to dynamically alter its behavior at runtime by delegating operations to its current state object.
• Mediator: Encapsulates how a set of objects interact by introducing a mediator object that centralizes complex communication logic.
• Visitor: Represents operations over a stable object structure as separate visitor objects, making new operations easier to add without changing element classes.

These categories help practitioners narrow down which pattern might apply: if the problem is about creating objects flexibly, look at creational patterns; if it is about structuring relationships between classes, look at structural patterns; if it is about coordinating behavior between objects, look at behavioral patterns.

Beyond the GoF: PLoP-era extensions

The Pattern Languages of Program Design (PLoP) series, edited by Coplien, Schmidt, and others, formalized many additional patterns that complement the GoF catalog. The most widely adopted is the Null Object pattern, written up by Bobby Woolf in PLoP3 (1998): provide a surrogate that shares the same interface as a real collaborator but does nothing meaningful. Null Object combines naturally with Strategy (Null Strategy), State (Null State), and Iterator (Null Iterator) — see Pattern Compounds below.

Code Example: Same Design Shape, Different Syntax

Design patterns are not language features. The same responsibility split can be expressed in Java, C++, Python, or TypeScript, with each language using its own idioms. This tiny action example has the same shape as a request object: a button stores something executable without knowing the concrete operation behind it.

Teaching example: These snippets are intentionally small. They show one reasonable mapping of the pattern roles, not a drop-in architecture. In production, always tailor the pattern to the concrete context: lifecycle, ownership, error handling, concurrency, dependency injection, language idioms, and team conventions.

interface Action {
    void execute();
}

final class SaveAction implements Action {
    public void execute() {
        System.out.println("Saving document");
    }
}

final class Button {
    private final Action action;

    Button(Action action) {
        this.action = action;
    }

    void click() {
        action.execute();
    }
}

public class Demo {
    public static void main(String[] args) {
        new Button(new SaveAction()).click();
    }
}

#include <iostream>

struct Action {
    virtual ~Action() = default;
    virtual void execute() = 0;
};

class SaveAction : public Action {
public:
    void execute() override {
        std::cout << "Saving document\n";
    }
};

class Button {
public:
    explicit Button(Action& action) : action_(action) {}

    void click() {
        action_.execute();
    }

private:
    Action& action_;
};

int main() {
    SaveAction save;
    Button(save).click();
}

from abc import ABC, abstractmethod


class Action(ABC):
    @abstractmethod
    def execute(self) -> None:
        pass


class SaveAction(Action):
    def execute(self) -> None:
        print("Saving document")


class Button:
    def __init__(self, action: Action) -> None:
        self._action = action

    def click(self) -> None:
        self._action.execute()


Button(SaveAction()).click()

interface Action {
  execute(): void;
}

class SaveAction implements Action {
  execute(): void {
    console.log("Saving document");
  }
}

class Button {
  constructor(private readonly action: Action) {}

  click(): void {
    this.action.execute();
  }
}

new Button(new SaveAction()).click();

Architectural Patterns

Architectural patterns operate at a higher level of abstraction than GoF design patterns. While GoF patterns deal with classes, objects, and method calls, architectural patterns constrain the gross structure of an entire system. As Taylor, Medvidović, and Dashofy frame it in Software Architecture: Foundations, Theory, and Practice (2009): architectural styles are strategic while patterns are tactical design tools—a style constrains the overall architectural decisions, while a pattern provides a concrete, parameterized solution fragment.

Here are some examples of architectural patterns that we describe in more detail:

• Model-View-Controller (MVC): The Model-View-Controller (MVC) architectural pattern decomposes an interactive application into three distinct components: a model that encapsulates the core application data and business logic, a view that renders this information to the user, and a controller that translates user inputs into corresponding state updates.

The Benefits of a Shared Toolbox

Just as a mechanic must know their toolbox, a software engineer must know design patterns intimately—understanding their advantages, disadvantages, and knowing precisely when (and when not) to use them.

• A Common Language for Communication: The primary challenge in multi-person software development is communication. Patterns solve this by providing a robust, shared vocabulary. If an engineer suggests using the “Observer” or “Strategy” pattern, the team instantly understands the problem, the proposed architecture, and the resulting interactions without needing a lengthy explanation.
• Capturing Design Intent: When you encounter a design pattern in existing code, it communicates not only what the software does, but why it was designed that way.
• Reusable Experience: Patterns are abstractions of design experience gathered by seasoned practitioners. By studying them, developers can rely on tried-and-tested methods to build flexible and maintainable systems instead of reinventing the wheel.

Challenges and Pitfalls of Design Patterns

Despite their power, design patterns are not silver bullets. Misusing them introduces severe challenges:

• The “Hammer and Nail” Syndrome: Novice developers who just learned patterns often try to apply them to every problem they see. Software quality is not measured by the number of patterns used. Often, keeping the code simple and avoiding a pattern entirely is the best solution. As Kent Beck advises: “Do the simplest thing that could possibly work.” This echoes Gall’s Law (John Gall, Systemantics, 1975): “A complex system that works is invariably found to have evolved from a simple system that worked. A complex system designed from scratch never works and cannot be patched up to make it work.”
• Over-engineering vs. Under-engineering: Under-engineering makes software too rigid for future changes. However, over-applying patterns leads to over-engineering—creating premature abstractions that make the codebase unnecessarily complex, unreadable, and a waste of development time. Developers must constantly balance simplicity (fewer classes and patterns) against changeability (greater flexibility but more abstraction).
• Implicit Dependencies: Patterns intentionally replace static, compile-time dependencies with dynamic, runtime interactions. This flexibility comes at a cost: it becomes harder to trace the execution flow and state of the system just by reading the code.
• Misinterpretation as Recipes: A pattern is an abstract idea, not a snippet of code from Stack Overflow. Integrating a pattern into a system is a human-intensive, manual activity that requires tailoring the solution to fit a concrete context. As Bass, Clements, and Kazman note: “Applying a pattern is not an all-or-nothing proposition. Pattern definitions given in catalogs are strict, but in practice architects may choose to violate them in small ways when there is a good design tradeoff to be had.”

Common Student Misconceptions

Research on teaching design patterns reveals specific, recurring pitfalls that learners should be aware of:

• Learning Structure but Not Intent: A design-structure-matrix study by Cai and Wong (CSEE&T 2011) of 85 student submissions found that 74% did not faithfully implement a modular design even though their software functioned correctly. Students learned the gross structure of patterns easily, yet they made lower-level mistakes that violated the pattern’s underlying intent—introducing extra dependencies that defeated the very modularity the pattern was meant to achieve. The lesson: correct behavior is not the same as correct design. A program can produce the right output while still being poorly structured for future change.
• Ignoring Evolution Scenarios: The true value of a design pattern is only realized as software evolves, but student assignments, once completed, seldom evolve. Without experiencing the pain of modifying tightly coupled code, it is hard to appreciate why a pattern matters. To internalize the value of patterns, try to imagine concrete future changes (e.g., “What if we need a new type of observer?” or “What if we need to swap the database?”) and evaluate whether the design would gracefully accommodate them.
• Confusing Patterns with Antipatterns: Just as patterns represent proven solutions, antipatterns represent common poor design choices—such as Spaghetti Code, God Class, or Lava Flow—that lead to maintainability and security issues. Recognizing antipatterns requires going beyond individual instructions into reasoning about how methods and classes are architected. Students should be exposed to both: patterns teach what good structure looks like, while antipatterns teach what to avoid.
• The “Before and After” Exercise: A powerful technique for internalizing patterns, reported by Astrachan et al. from the first UP (Using Patterns) conference, involves taking a working solution that does not use a pattern and then refactoring it to introduce the appropriate pattern. By comparing the “before” and “after” versions—particularly when extending both with a new requirement—the concrete advantages of the pattern become viscerally clear. As the adage goes: “Good design comes from experience, and experience comes from bad design.”

Context Tailoring

It is important to remember that the standard description of a pattern presents an abstract solution to an abstract problem. Integrating a pattern into a software system is a highly human-intensive, manual activity; patterns cannot simply be misinterpreted as step-by-step recipes or copied as raw code. Instead, developers must engage in context tailoring—the process of taking an abstract pattern and instantiating it into a concrete solution that perfectly fits the concrete problem and the concrete context of their application.

Because applying a pattern outside of its intended problem space can result in bad design (such as the notorious over-use of the Singleton pattern), tailoring ensures that the pattern acts as an effective tool rather than an arbitrary constraint.

The Tailoring Process: The Measuring Tape and the Scissors

Context tailoring can be understood through the metaphor of making a custom garment, which requires two primary steps: using a “measuring tape” to observe the context, and using “scissors” to make the necessary adjustments.

1. Observation of Context

Before altering a design pattern, you must thoroughly observe and measure the environment in which it will operate. This involves analyzing three main areas:

• Project-Specific Needs: What kind of evolution is expected? What features are planned for the future, and what frameworks is the system currently relying on?
• Desired System Properties: What are the overarching goals of the software? Must the architecture prioritize run-time performance, strict security, or long-term maintainability?
• The Periphery: What is the complexity of the surrounding environment? Which specific classes, objects, and methods will directly interact with the pattern’s participants?

2. Making Adjustments

Once the context is mapped, developers must “cut” the pattern to fit. This requires considering the broad design space of the pattern and exploring its various alternatives and variation points. After evaluating the context-specific consequences of these potential variations, the developer implements the most suitable version. Crucially, the design decisions and the rationale behind those adjustments must be thoroughly documented. Without documentation, future developers will struggle to understand why a pattern deviates from its textbook structure.

Dimensions of Variation

Every design pattern describes a broad design space containing many distinct variations. When tailoring a pattern, developers typically modify it along four primary dimensions:

Structural Variations

These variations alter the roles and responsibility assignments defined in the abstract pattern, directly impacting how the system can evolve. For example, the Factory Method pattern can be structurally varied by removing the abstract product class entirely. Instead, a single concrete product is implemented and configured with different parameters. This variation trades the extensibility of a massive subclass hierarchy for immediate simplicity.

Behavioral Variations

Behavioral variations modify the interactions and communication flows between objects. These changes heavily impact object responsibilities, system evolution, and run-time quality attributes like performance. A classic example is the Observer pattern, which can be tailored into a “Push model” (where the subject pushes all updated data directly to the observer) or a “Pull model” (where the subject simply notifies the observer, and the observer must pull the specific data it needs).

Internal Variations

These variations involve refining the internal workings of the pattern’s participants without necessarily changing their external structural interfaces. A developer might tailor a pattern internally by choosing a specific list data structure to hold observers, adding thread-safety mechanisms, or implementing a specialized sorting algorithm to maximize performance for expected data sets.

Language-Dependent Variations

Modern programming languages offer specific constructs that can drastically simplify pattern implementations. For instance, dynamically typed languages can often omit explicit interfaces, and aspect-oriented languages can replace standard polymorphism with aspects and point-cuts. However, there is a dangerous trap here: using language features to make a pattern entirely reusable as code (e.g., using include Singleton in Ruby) eliminates the potential for context tailoring. Design patterns are fundamentally about design reuse, not exact code reuse.

The Global vs. Local Optimum Trade-off

While context tailoring is essential, it introduces a significant challenge in large-scale software projects. Perfectly tailoring a pattern to every individual sub-problem creates a “local optimum”. However, a large amount of pattern variation scattered throughout a single project can lead to severe confusion due to overloaded meaning.

If developers use the textbook Observer pattern in one module, but highly customized, structurally varied Observers in another, incoming developers might falsely assume identical behavior simply because the classes share the “Observer” naming convention. To mitigate this, large teams must rely on project conventions to establish pattern consistency. Teams must explicitly decide whether to embrace diverse, highly tailored implementations (and name them distinctly) or to enforce strict guidelines on which specific pattern variants are permitted within the codebase.

Pattern Compounds

In software design, applying individual design patterns is akin to utilizing distinct compositional techniques in photography—such as symmetry, color contrast, leading lines, and a focal object. Simply having these patterns present does not guarantee a masterpiece; their deliberate arrangement is crucial. When leading lines intentionally point toward a focal object, a more pleasing image emerges. In software architecture, this synergistic combination is known as a pattern compound—a term coined by Dirk Riehle in Composite Design Patterns (OOPSLA 1997), where the recurring superimpositions of GoF roles (Composite Builder, Composite Visitor, Singleton State) were first systematically catalogued.

A pattern compound is a reoccurring set of patterns with overlapping roles from which additional properties emerge. Notably, pattern compounds are patterns in their own right, complete with an abstract problem, an abstract context, and an abstract solution. While pattern languages provide a meta-level conceptual framework or grammar for how patterns relate to one another, pattern compounds are concrete structural and behavioral unifications.

The Anatomy of Pattern Compounds

The core characteristic of a pattern compound is that the participating domain classes take on multiple superimposed roles simultaneously. By explicitly connecting patterns, developers can leverage one pattern to solve a problem created by another, leading to a new set of emergent properties and consequences.

Solving Structural Complexity: The Composite Builder

The Composite pattern is excellent for creating unified tree structures, but initializing and assembling this abstract object structure is notoriously difficult. The Builder pattern, conversely, is designed to construct complex object structures. By combining them, the Composite’s Component plays the role of the Builder’s Product abstraction, while Leaf and Composite are the concrete pieces the builder assembles into the resulting tree.

This compound yields the emergent properties of looser coupling between the client and the composite structure and the ability to create different representations of the encapsulated composite. However, as a trade-off, dealing with a recursive data structure within a Builder introduces even more complexity than using either pattern individually.

Managing Operations: The Composite Visitor and Composite Command

Pattern compounds frequently emerge when scaling behavioral patterns to handle structural complexity:

• Composite Visitor: If a system requires many custom operations to be defined on a Composite structure without modifying the classes themselves (and no new leaves are expected), a Visitor can be superimposed. This yields the emergent property of strict separation of concerns, keeping core structural elements distinct from use-case-specific operations.
• Composite Command: When a system involves hierarchical actions that require a simple execution API, a Composite Command groups multiple command objects into a unified tree. This allows individual command pieces to be shared and reused, though developers must manage the consequence of execution order ambiguity.

Communicating Design Intent and Context Tailoring

Pattern compounds also naturally arise when tailoring patterns to specific contexts or when communicating highly specific design intents.

• Null State / Null Strategy: If an object enters a “do nothing” state, combining the State pattern with the Null Object pattern perfectly communicates the design intent of empty behavior. (Note that there is no Null Decorator, as a decorator must fully implement the interface of the decorated object).
• Singleton Null Object: Because Null Objects are typically stateless, the canonical implementation shares one instance — making Null Object and Singleton one of the most frequent compounds in real codebases.
• Singleton State: If State objects are entirely stateless—meaning they carry behavior but no data, and do not require a reference back to their Context—they can be implemented as Singletons. This tailoring decision saves memory and eases object creation, though it permanently couples the design by removing the ability to reference the Context in the future.

The Advantages of Compounding Patterns

The primary advantage of pattern compounds is that they make software design more coherent. Instead of finding highly optimized but fragmented patchwork solutions for every individual localized problem, compounds provide overarching design ideas and unifying themes. They raise the composition of patterns to a higher semantic abstraction, enabling developers to systematically foresee how the consequences of one pattern map directly to the context of another.

Challenges and Pitfalls

Despite their power, pattern compounds introduce distinct architectural and cognitive challenges:

• Mixed Concerns: Because pattern compounds superimpose overlapping roles, a single class might juggle three distinct concerns: its core domain functionality, its responsibility in the first pattern, and its responsibility in the second. This can severely overload a class and muddle its primary responsibility.
• Obscured Foundations: Tightly compounding patterns can make it much harder for incoming developers to visually identify the individual, foundational patterns at play.
• Naming Limitations: Accurately naming a class to reflect its domain purpose alongside multiple pattern roles (e.g., a “PlayerObserver”) quickly becomes unmanageable, forcing teams to rely heavily on external documentation to explain the architecture.
• The Over-Engineering Trap: As with any design abstraction, possessing the “hammer” of a pattern compound does not make every problem a nail. Developers must constantly evaluate whether the resulting architectural complexity is truly justified by the context.

Design Patterns and Refactoring

Design patterns and refactoring are deeply connected. As Tokuda and Batory demonstrated, refactorings are behavior-preserving program transformations that can automate the evolution of a design toward a pattern. The principle is straightforward: designs should evolve on an if-needed basis. Rather than speculating upfront about which patterns might be needed, start with the simplest working solution and refactor toward a pattern when code smells indicate the need.

Common code smells that suggest specific patterns:

The Rule of Three provides a useful heuristic: do not apply a pattern until you have seen the need at least three times. This prevents speculative abstraction—creating flexibility for variation points that may never actually vary.

Advanced Concepts

Patterns Within Patterns: Core Principles

When analyzing various design patterns, you will begin to notice recurring micro-architectures. Design patterns are often built upon fundamental software engineering principles:

• Delegation over Inheritance: Subclassing can lead to rigid designs and code duplication (e.g., trying to create an inheritance tree for cars that can be electric, gas, hybrid, and also either drive or fly). Patterns like Strategy, State, and Bridge solve this by extracting varying behaviors into separate classes and delegating responsibilities to them.
• Polymorphism over Conditions: Patterns frequently replace complex if/else or switch statements with polymorphic objects. For instance, instead of conditional logic checking the state of an algorithm, the Strategy pattern uses interchangeable objects to represent different execution paths.
• Additional Layers of Indirection: To reduce strong coupling between interacting components, patterns like the Mediator or Façade introduce an intermediate object to handle communication. While this centralizes logic and improves changeability, it can create long traces of method calls that are harder to debug.

Domain-Specific and Application-Specific Patterns

The Gang of Four patterns are generic to object-oriented programming, but patterns exist at all levels.

• Domain-Specific Patterns: Certain industries (like Game Development, Android Apps, or Security) have their own highly tailored patterns. Because these patterns make assumptions about a specific domain, they generally carry fewer negative consequences within their niche, but they require the team to actually possess domain expertise.
• Application-Specific Patterns: Every distinct software project will eventually develop its own localized patterns—agreed-upon conventions and structures unique to that team. Identifying and documenting these implicit patterns is one of the most critical steps when a new developer joins an existing codebase, as it massively improves program comprehension.

Conclusion

Design patterns are the foundational building blocks of robust software architecture. However, they are not a substitute for domain expertise or critical thought. The mark of an expert engineer is not knowing how to implement every pattern, but possessing the wisdom to evaluate trade-offs, carefully observe the context, and know exactly when the simplest code is actually the smartest design.

Practice

Problem

Many classes differ only in how they perform a particular task. A duck simulator needs many duck types that all swim and display, but each one flies and quacks differently. A text composer needs to break paragraphs into lines, but the linebreaking algorithm should be selectable: a fast greedy pass for an interactive editor, the TeX algorithm for high-quality typesetting, or a fixed-width strategy for icon grids. A payment system needs credit card, PayPal, and bank-transfer flows that all share the same checkout pipeline.

If you push every variant into a single class with conditional logic, the class quickly becomes unmaintainable:

class Duck {
    void fly(String type) {
        if (type.equals("mallard")) {
            // flap wings
        } else if (type.equals("rubber")) {
            // do nothing
        } else if (type.equals("decoy")) {
            // do nothing
        } else if (type.equals("rocket")) {
            // launch rockets
        }
        // every new duck adds another branch
    }
}

If you push every variant into its own subclass, you end up with deep inheritance hierarchies that fight reality: a RubberDuck inherits a fly() it must override to do nothing; a DecoyDuck inherits both fly() and quack() it must neutralize. Adding a new behavior axis (e.g., “swim with rockets”) combinatorially explodes the class hierarchy.

The core problem is: How can we vary an algorithm independently of the objects that use it, swap algorithms at runtime, and add new algorithms without touching existing client code?

Context

The Strategy pattern (also known as the Policy pattern (Gamma et al. 1995)) applies when:

• Many related classes differ only in their behavior. Strategies provide a way to configure a class with one of many behaviors, instead of creating a subclass for each behavior (Gamma et al. 1995).
• You need different variants of an algorithm. For example, algorithms that reflect different space/time trade-offs, or algorithms tuned for different data shapes.
• An algorithm uses data that clients shouldn’t know about. Hiding algorithm-specific data structures behind a Strategy interface keeps clients decoupled from implementation details.
• A class defines many behaviors that appear as multiple conditional statements. Move the conditional branches into their own Strategy classes so each branch becomes a polymorphic object (Freeman and Robson 2020).

Common applications include sorting and searching algorithms, validation rules, compression formats, payment processing flows, AI agents in games, layout/linebreaking strategies in text editors, and authentication schemes.

Solution

The Strategy pattern defines a family of algorithms, encapsulates each one as an object, and makes them interchangeable at runtime. The client (the Context) holds a reference to a Strategy interface and delegates the variable behavior to it.

The pattern involves three roles:

1. Strategy: An interface (or abstract class) declaring the operation common to all supported algorithms. The Context uses this interface to invoke the algorithm.
2. ConcreteStrategy: A class that implements the Strategy interface with one specific algorithm.
3. Context: The class that uses the algorithm. It holds a reference to a Strategy object and forwards work to it. The Context typically exposes a setter so the strategy can be swapped at runtime.

The key insight is composition over inheritance: instead of locking each variant into a subclass, the Context has-a Strategy and can be re-configured at any time. This is the same insight that makes the Observer and State patterns work — replace static class hierarchies with dynamic object delegation.

UML Role Diagram

Figure: the Context aggregates a Strategy and forwards work to it; ConcreteStrategies realize the interface independently. The Context never knows which concrete strategy it holds.

UML Example Diagram

The classic SimUDuck example (Freeman and Robson 2020) extracts the fly and quack behaviors out of the Duck hierarchy. Each duck has-a FlyBehavior and a QuackBehavior; the concrete strategy classes implement each variation. A MallardDuck flies with wings and quacks normally; a RubberDuck cannot fly (uses a null-object fly behavior) and squeaks instead. (The book itself names the no-op fly strategy FlyNoWay; we use FlyNullObject here to make its design role as a Null Object explicit.)

Figure: Duck delegates flying and quacking to interchangeable Strategy objects; RubberDuck swaps in FlyNullObject instead of subclassing to override.

Sequence Diagram

This sequence shows runtime reconfiguration: a ModelDuck starts with a no-op fly behavior, the client swaps in a rocket-powered strategy via setFlyBehavior, and the next performFly() call now does something completely different — without changing the Duck class.

Figure: the same Duck object exhibits two different fly behaviors across two performFly() calls — runtime swapping is the central capability Strategy enables.

Code Example

This example follows the SimUDuck design from Head First Design Patterns (Freeman and Robson 2020). The Duck class delegates to two strategy objects; concrete duck subclasses configure their strategies in the constructor; the client can swap a strategy at runtime by calling setFlyBehavior().

Teaching example: These snippets are intentionally small. They show one reasonable mapping of the pattern roles, not a drop-in architecture. In production, always tailor the pattern to the concrete context: lifecycle, ownership, error handling, concurrency, dependency injection, language idioms, and team conventions.

interface FlyBehavior {
    void fly();
}

interface QuackBehavior {
    void quack();
}

final class FlyWithWings implements FlyBehavior {
    public void fly() {
        System.out.println("Flapping wings");
    }
}

final class FlyNullObject implements FlyBehavior {
    public void fly() {
        // do nothing — can't fly
    }
}

final class FlyRocketPowered implements FlyBehavior {
    public void fly() {
        System.out.println("Flying with a rocket");
    }
}

final class Quack implements QuackBehavior {
    public void quack() {
        System.out.println("Quack!");
    }
}

abstract class Duck {
    protected FlyBehavior flyBehavior;
    protected QuackBehavior quackBehavior;

    void performFly() {
        flyBehavior.fly();
    }

    void performQuack() {
        quackBehavior.quack();
    }

    void setFlyBehavior(FlyBehavior fb) {
        this.flyBehavior = fb;
    }

    abstract void display();
}

final class ModelDuck extends Duck {
    ModelDuck() {
        flyBehavior = new FlyNullObject();
        quackBehavior = new Quack();
    }

    void display() {
        System.out.println("I'm a model duck");
    }
}

public class Demo {
    public static void main(String[] args) {
        Duck model = new ModelDuck();
        model.performFly();                          // does nothing
        model.setFlyBehavior(new FlyRocketPowered());
        model.performFly();                          // "Flying with a rocket"
    }
}

#include <iostream>
#include <memory>

struct FlyBehavior {
    virtual ~FlyBehavior() = default;
    virtual void fly() = 0;
};

struct QuackBehavior {
    virtual ~QuackBehavior() = default;
    virtual void quack() = 0;
};

class FlyWithWings : public FlyBehavior {
public:
    void fly() override { std::cout << "Flapping wings\n"; }
};

class FlyNullObject : public FlyBehavior {
public:
    void fly() override { /* do nothing */ }
};

class FlyRocketPowered : public FlyBehavior {
public:
    void fly() override { std::cout << "Flying with a rocket\n"; }
};

class Quack : public QuackBehavior {
public:
    void quack() override { std::cout << "Quack!\n"; }
};

class Duck {
public:
    virtual ~Duck() = default;

    void performFly() { flyBehavior_->fly(); }
    void performQuack() { quackBehavior_->quack(); }

    void setFlyBehavior(std::unique_ptr<FlyBehavior> fb) {
        flyBehavior_ = std::move(fb);
    }

    virtual void display() const = 0;

protected:
    std::unique_ptr<FlyBehavior> flyBehavior_;
    std::unique_ptr<QuackBehavior> quackBehavior_;
};

class ModelDuck : public Duck {
public:
    ModelDuck() {
        flyBehavior_ = std::make_unique<FlyNullObject>();
        quackBehavior_ = std::make_unique<Quack>();
    }

    void display() const override { std::cout << "I'm a model duck\n"; }
};

int main() {
    ModelDuck model;
    model.performFly();                                            // does nothing
    model.setFlyBehavior(std::make_unique<FlyRocketPowered>());
    model.performFly();                                            // "Flying with a rocket"
}

from abc import ABC, abstractmethod


class FlyBehavior(ABC):
    @abstractmethod
    def fly(self) -> None:
        pass


class QuackBehavior(ABC):
    @abstractmethod
    def quack(self) -> None:
        pass


class FlyWithWings(FlyBehavior):
    def fly(self) -> None:
        print("Flapping wings")


class FlyNullObject(FlyBehavior):
    def fly(self) -> None:
        pass  # do nothing — can't fly


class FlyRocketPowered(FlyBehavior):
    def fly(self) -> None:
        print("Flying with a rocket")


class Quack(QuackBehavior):
    def quack(self) -> None:
        print("Quack!")


class Duck(ABC):
    def __init__(self) -> None:
        self.fly_behavior: FlyBehavior
        self.quack_behavior: QuackBehavior

    def perform_fly(self) -> None:
        self.fly_behavior.fly()

    def perform_quack(self) -> None:
        self.quack_behavior.quack()

    def set_fly_behavior(self, fb: FlyBehavior) -> None:
        self.fly_behavior = fb

    @abstractmethod
    def display(self) -> None:
        pass


class ModelDuck(Duck):
    def __init__(self) -> None:
        super().__init__()
        self.fly_behavior = FlyNullObject()
        self.quack_behavior = Quack()

    def display(self) -> None:
        print("I'm a model duck")


model = ModelDuck()
model.perform_fly()                            # does nothing
model.set_fly_behavior(FlyRocketPowered())
model.perform_fly()                            # "Flying with a rocket"

interface FlyBehavior {
  fly(): void;
}

interface QuackBehavior {
  quack(): void;
}

class FlyWithWings implements FlyBehavior {
  fly(): void { console.log("Flapping wings"); }
}

class FlyNullObject implements FlyBehavior {
  fly(): void { /* do nothing — can't fly */ }
}

class FlyRocketPowered implements FlyBehavior {
  fly(): void { console.log("Flying with a rocket"); }
}

class Quack implements QuackBehavior {
  quack(): void { console.log("Quack!"); }
}

abstract class Duck {
  protected flyBehavior!: FlyBehavior;
  protected quackBehavior!: QuackBehavior;

  performFly(): void {
    this.flyBehavior.fly();
  }

  performQuack(): void {
    this.quackBehavior.quack();
  }

  setFlyBehavior(fb: FlyBehavior): void {
    this.flyBehavior = fb;
  }

  abstract display(): void;
}

class ModelDuck extends Duck {
  constructor() {
    super();
    this.flyBehavior = new FlyNullObject();
    this.quackBehavior = new Quack();
  }

  display(): void {
    console.log("I'm a model duck");
  }
}

const model = new ModelDuck();
model.performFly();                          // does nothing
model.setFlyBehavior(new FlyRocketPowered());
model.performFly();                          // "Flying with a rocket"

In languages with first-class functions, a strategy is often just a function — Comparator<T> in Java (often written as a lambda like (a, b) -> a.getName().compareTo(b.getName())), a key function passed to Python’s sorted(key=...), a lambda passed to Array.prototype.sort. Use an explicit Strategy class when the algorithm needs identity, configuration data, multiple operations, polymorphic dispatch beyond a single call, or test seams.

Design Decisions

How does the Strategy access Context data?

When a Strategy needs information from the Context to do its job, there are two main approaches (Gamma et al. 1995):

• Pass data as parameters: The Context passes everything the Strategy needs through the algorithm interface (e.g., compose(componentSizes, lineWidth, breaks)). This keeps Strategy and Context decoupled, but the Context may have to pass data the Strategy doesn’t actually need.
• Pass the Context itself: The Context passes itself as an argument, and the Strategy queries the Context for whatever data it needs (e.g., strategy.execute(this)). This lets the Strategy ask for exactly what it wants but requires Context to expose a richer interface, increasing coupling.

The right choice depends on the algorithm’s data needs and how stable the Context’s interface is.

Compile-time vs. runtime strategy selection

• Runtime selection (the standard form): the Strategy is held as a field and can be swapped via a setter. This enables dynamic reconfiguration — exactly what setFlyBehavior() enables in the duck example.
• Compile-time selection (C++ template parameter, generics): the Strategy is bound when the type is instantiated — known as policy-based design in C++. This is more efficient (no virtual dispatch, possibly inlinable) but cannot change at runtime. Useful when the choice is fixed at configuration time and performance matters (Gamma et al. 1995).

Optional Strategy with default behavior

The Context can be simplified if it’s meaningful for the Strategy reference to be absent. The Context checks if a Strategy is set: if so, it delegates; if not, it falls back to a default behavior (Gamma et al. 1995). Clients that want the default never have to deal with Strategy objects at all. The Null Object variant (e.g., FlyNullObject) achieves the same effect more uniformly: a “do nothing” Strategy keeps the Context’s call site simple (flyBehavior.fly()) without null checks.

Stateless vs. stateful strategies

If a Strategy carries no instance data, it can be shared across many Contexts as a Flyweight or Singleton, saving memory and avoiding repeated allocation. If it carries per-Context configuration (e.g., a RangeValidator(min=0, max=100)), each Context needs its own Strategy instance.

Consequences

Applying the Strategy pattern yields several important consequences (Gamma et al. 1995):

• Families of related algorithms. Strategy hierarchies define a family of interchangeable algorithms. Common functionality can be factored out via inheritance among ConcreteStrategies.
• An alternative to subclassing. Rather than baking each algorithm variant into a Context subclass — which couples algorithm and Context tightly — Strategy encapsulates each algorithm separately. The Context becomes simpler, and algorithms can vary independently.
• Eliminates conditional statements. Code with many if/switch branches selecting between algorithms is a strong code smell pointing to Strategy. Each branch becomes a polymorphic ConcreteStrategy. This is the polymorphism over conditions principle that also underlies the State pattern.
• A choice of implementations. Strategies can provide different implementations of the same behavior with different time/space trade-offs (e.g., a fast approximate sort vs. a careful stable sort), letting the client choose.
• Clients must know about the strategies. Because the client typically picks the ConcreteStrategy, it must understand how the strategies differ. If the choice should be hidden from clients, Strategy is the wrong tool.
• Communication overhead. The Strategy interface is shared by all ConcreteStrategies. Some may not need all the data the interface passes, leading to wasted preparation in the Context.
• Increased number of objects. Strategy adds one class per algorithm variant. Stateless strategies can be shared as flyweights to mitigate this.

Strategy vs. Related Patterns

A useful heuristic distinguishing Strategy from State: ask whether the client picks the implementation (Strategy) or whether the object’s own internal logic picks it (State). If a GumballMachine switches from NoQuarterState to HasQuarterState because the user inserted a coin, that’s State. If a sort routine accepts a Comparator parameter, that’s Strategy.

Pattern Compounds and Idioms

Strategy combines naturally with other patterns:

• Strategy + Singleton / Flyweight: Stateless strategies (e.g., Quack, Squeak) carry behavior but no data. They can be implemented as singletons or shared as flyweights to avoid creating one instance per Context.
• Null Strategy: A “do nothing” ConcreteStrategy (e.g., FlyNullObject, MuteQuack) replaces null checks in the Context with uniform polymorphic dispatch. This is the Null Object pattern superimposed on Strategy.
• Strategy + Factory Method / Abstract Factory: A factory selects which ConcreteStrategy to instantiate based on configuration, environment, or feature flags — keeping the Context oblivious to selection logic.
• Strategy in MVC: In the MVC compound pattern, the Controller is a Strategy used by the View. Swapping controllers (e.g., from an editing controller to a read-only controller) reconfigures input behavior without modifying the View.

Common Examples

Practical Guidance: When NOT to Use Strategy

Strategy is not free. Skip it when:

• There is only one algorithm. A single concrete class with a single method is simpler. Don’t create an interface and subclass for a variant that doesn’t exist yet — that’s speculative abstraction.
• The variants will never change at runtime and clients don’t care. A simple inheritance hierarchy or even a parameter switch may be clearer.
• The strategies are trivial one-liners. A function or lambda is often enough; the boilerplate of a class hierarchy is unjustified.
• The choice is genuinely a state machine. If “which algorithm” depends on what the object is currently doing, State is the right tool — the structure looks identical but the intent differs.

As with all design patterns, keep the Rule of Three in mind: don’t introduce Strategy until you have at least three concrete variants or a clear plan for runtime swapping. The simplest code is usually the smartest design.

Flashcards

Quiz

class FlyNullObject implements FlyBehavior {
    public void fly() { /* do nothing */ }
}

Want hands-on practice? Try the Interactive Observer Pattern Tutorial — experience the pain of tight coupling first, then refactor into Observer step by step with live UML diagrams, debugging challenges, and quizzes.

Problem 

In software design, you frequently encounter situations where one object’s state changes, and several other objects need to be notified of this change so they can update themselves accordingly. As the Gang of Four (GoF — the four authors of Design Patterns (Gamma et al. 1995)) describe it, this is a common side-effect of partitioning a system into a collection of cooperating classes: you need to maintain consistency between related objects, but you don’t want to achieve that consistency by making the classes tightly coupled, because that reduces their reusability.

The classic motivating example (GoF Observer chapter) is a graphical user interface toolkit that separates presentation from the underlying application data: a spreadsheet view and a bar chart can both depict the same numerical data using different presentations. The two views don’t know about each other, yet they must behave as though they do — when the user edits a value in the spreadsheet, the bar chart must reflect the change immediately, and vice versa. There is no reason to limit the number of dependents to two; any number of different views may want to display the same data.

If the dependent objects constantly check the core object for changes (polling), it wastes valuable CPU cycles and resources. Conversely, if the core object is hard-coded to directly update all its dependent objects, the classes become tightly coupled. Every time you need to add or remove a dependent object, you have to modify the core object’s code, violating the Open/Closed Principle.

The core problem is: How can a one-to-many dependency between objects be maintained efficiently without making the objects tightly coupled?

Intent (GoF): “Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically.”

Also Known As: Dependents, Publish-Subscribe (the GoF Observer chapter explicitly lists both as alternative names; POSA1 (Buschmann et al. 1996) documents the related pattern under the name Publisher-Subscriber, with Observer and Dependents as aliases).

Context

The Observer pattern is highly applicable in scenarios requiring distributed event handling systems or highly decoupled architectures. Common contexts include:

• User Interfaces (GUI): A classic example is the Model-View-Controller (MVC) architecture. When the underlying data (Model) changes, multiple UI components (Views) like charts, tables, or text fields must update simultaneously to reflect the new data.

• Event Management Systems: Applications that rely on events—such as user button clicks, incoming network requests, or file system changes—where an unknown number of listeners might want to react to a single event.

• Social Media/News Feeds: A system where users (observers) follow a specific creator (subject) and need to be notified instantly when new content is posted.

Solution

The Observer design pattern solves this by establishing a one-to-many subscription mechanism.

It introduces two main roles: the Subject (the object sending updates after it has changed) and the Observer (the object listening to the updates of Subjects).

Instead of objects polling the Subject or the Subject being hard-wired to specific objects, the Subject maintains a dynamic list of Observers. It provides an interface for Observers to attach and detach themselves at runtime. When the Subject’s state changes, it iterates through its list of attached Observers and calls a specific notification method (e.g., update()) defined in the Observer interface.

This creates a loosely coupled system: the Subject only knows that its Observers implement a specific interface, not their concrete implementation details.

UML Role Diagram

UML Example Diagram

Sequence Diagram

This pattern is fundamentally about runtime collaboration, so a sequence diagram is helpful here.

Code Example

This sample implements the pull-style News Channel example from the diagrams. The subject sends a simple notification; each observer asks the subject for the latest post.

Teaching example: These snippets are intentionally small. They show one reasonable mapping of the pattern roles, not a drop-in architecture. In production, always tailor the pattern to the concrete context: lifecycle, ownership, error handling, concurrency, dependency injection, language idioms, and team conventions.

import java.util.ArrayList;
import java.util.List;

interface Subscriber {
    void update();
}

final class NewsChannel {
    private final List<Subscriber> subscribers = new ArrayList<>();
    private String latestPost = "";

    void follow(Subscriber subscriber) {
        subscribers.add(subscriber);
    }

    void unfollow(Subscriber subscriber) {
        subscribers.remove(subscriber);
    }

    void publishPost(String text) {
        latestPost = text;
        subscribers.forEach(Subscriber::update);
    }

    String getLatestPost() {
        return latestPost;
    }
}

final class MobileApp implements Subscriber {
    private final NewsChannel channel;

    MobileApp(NewsChannel channel) {
        this.channel = channel;
    }

    public void update() {
        System.out.println("[MobileApp] " + channel.getLatestPost());
    }
}

final class EmailDigest implements Subscriber {
    private final NewsChannel channel;

    EmailDigest(NewsChannel channel) {
        this.channel = channel;
    }

    public void update() {
        System.out.println("[EmailDigest] " + channel.getLatestPost());
    }
}

public class Demo {
    public static void main(String[] args) {
        NewsChannel channel = new NewsChannel();
        Subscriber app = new MobileApp(channel);
        Subscriber email = new EmailDigest(channel);
        channel.follow(app);
        channel.follow(email);
        channel.publishPost("New video uploaded!");
        channel.unfollow(email);
        channel.publishPost("Live stream starting!");
    }
}

#include <algorithm>
#include <iostream>
#include <string>
#include <utility>
#include <vector>

struct Subscriber {
    virtual ~Subscriber() = default;
    virtual void update() = 0;
};

class NewsChannel {
public:
    void follow(Subscriber& subscriber) {
        subscribers_.push_back(&subscriber);
    }

    void unfollow(Subscriber& subscriber) {
        subscribers_.erase(
            std::remove(subscribers_.begin(), subscribers_.end(), &subscriber),
            subscribers_.end());
    }

    void publishPost(std::string text) {
        latestPost_ = std::move(text);
        for (auto* subscriber : subscribers_) {
            subscriber->update();
        }
    }

    const std::string& latestPost() const {
        return latestPost_;
    }

private:
    std::vector<Subscriber*> subscribers_;
    std::string latestPost_;
};

class MobileApp : public Subscriber {
public:
    explicit MobileApp(const NewsChannel& channel) : channel_(channel) {}

    void update() override {
        std::cout << "[MobileApp] " << channel_.latestPost() << "\n";
    }

private:
    const NewsChannel& channel_;
};

class EmailDigest : public Subscriber {
public:
    explicit EmailDigest(const NewsChannel& channel) : channel_(channel) {}

    void update() override {
        std::cout << "[EmailDigest] " << channel_.latestPost() << "\n";
    }

private:
    const NewsChannel& channel_;
};

int main() {
    NewsChannel channel;
    MobileApp app(channel);
    EmailDigest email(channel);
    channel.follow(app);
    channel.follow(email);
    channel.publishPost("New video uploaded!");
    channel.unfollow(email);
    channel.publishPost("Live stream starting!");
}

from abc import ABC, abstractmethod


class Subscriber(ABC):
    @abstractmethod
    def update(self) -> None:
        pass


class NewsChannel:
    def __init__(self) -> None:
        self._subscribers: list[Subscriber] = []
        self._latest_post = ""

    def follow(self, subscriber: Subscriber) -> None:
        self._subscribers.append(subscriber)

    def unfollow(self, subscriber: Subscriber) -> None:
        self._subscribers.remove(subscriber)

    def publish_post(self, text: str) -> None:
        self._latest_post = text
        for subscriber in self._subscribers:
            subscriber.update()

    def get_latest_post(self) -> str:
        return self._latest_post


class MobileApp(Subscriber):
    def __init__(self, channel: NewsChannel) -> None:
        self._channel = channel

    def update(self) -> None:
        print(f"[MobileApp] {self._channel.get_latest_post()}")


class EmailDigest(Subscriber):
    def __init__(self, channel: NewsChannel) -> None:
        self._channel = channel

    def update(self) -> None:
        print(f"[EmailDigest] {self._channel.get_latest_post()}")


channel = NewsChannel()
app = MobileApp(channel)
email = EmailDigest(channel)
channel.follow(app)
channel.follow(email)
channel.publish_post("New video uploaded!")
channel.unfollow(email)
channel.publish_post("Live stream starting!")