Example mapping

What it is

Matt Wynne — co-founder of Cucumber and co-author of The Cucumber Book — introduced example mapping in Introducing Example Mapping on the Cucumber blog in December 2015. The post was a response to a pattern Wynne was seeing across teams: stories entering the sprint felt “ready” to the product owner but arrived at the developer’s desk still ambiguous. The BDD three-amigos conversation helped but took too long and happened too rarely. Example mapping was a shorter, more focused technique that could run during routine backlog refinement and catch the same ambiguity.

The mechanics are deliberately simple. Four sticky-note colors, each with a specific role:

• Yellow — the user story. One per session.
• Blue — rules or constraints the story is governed by. What are the business rules?
• Green — concrete examples of each rule. “If X happens, the system does Y.” A rule without an example is suspect.
• Red — questions the team can’t answer on the spot. The team marker for “this isn’t ready.”

The session runs for 20–30 minutes. The team walks the story: what’s the story, what rules does it follow, give me an example of each rule, what questions can’t we answer? When the session ends:

• If there are no red cards, the story is ready. The green examples become acceptance criteria (often literally, word-for-word, in a BDD tool like Cucumber).
• If there are some red cards but the team is confident they can resolve them before sprint starts, the story is nearly-ready and the product owner owns the questions.
• If there are many red cards — more than the team can resolve before the sprint — the story is not ready. Park it, resolve the questions, bring it back to example mapping later.

The genius is that red-card count is an objective readiness signal. The product owner can’t self-assess a story as “ready” if the team has put up five red cards. Ambiguity becomes visible in a way that a backlog-tool’s “ready” checkbox can’t fake.

Example mapping is a BDD-family technique but doesn’t require BDD to be useful. It pairs naturally with Gherkin-style acceptance criteria — green examples drop into “Given/When/Then” scenarios cleanly — but a team that isn’t writing BDD scenarios still benefits from the conversation.

When to use it

Reach for example mapping when:

• A story is entering refinement and the team wants a fast check that it’s ready. Twenty to thirty minutes during a refinement session is often the highest-leverage thirty minutes of the sprint.
• The team keeps discovering mid-sprint that stories were less clear than they seemed at planning. The pattern is ambiguity surviving refinement because refinement was too cursory. Example mapping catches it earlier.
• A product owner wants to sharpen acceptance criteria but a full BDD three-amigos session would take longer than available. Example mapping is the lighter-weight variant.
• The team uses BDD tools (Cucumber, SpecFlow, Behave) and needs structured material to write Given/When/Then scenarios from. Green cards convert to scenarios naturally.
• A story has been bouncing between refinement sessions without converging. Example mapping exposes why — usually too many red cards, or rules without examples. Makes the lack of convergence visible.

Don’t reach for example mapping when:

• The story is genuinely simple and well-understood — a typo fix, a config change, a small refactor. Running example mapping on it is theater.
• The scope is wrong altogether. Example mapping works story-level; product-level or journey-level scope needs the event storming workshop or journey mapping.
• The three amigos aren’t available — specifically, without a business-side participant, the rules and examples get defined by engineers alone and miss the point. At minimum: one engineer, one business/product, one testing/QA perspective.
• The story’s complexity is architectural, not behavioral. A story like “migrate from database X to database Y” has few business rules and lots of technical risk. Example mapping produces nothing useful; reach for a pre-mortem or a spike instead.

How to run it

Total time: 25 minutes per story. Can flex to 15 for simple stories or 40 for complex ones, but the discipline is to hold the time-box tight enough that the team doesn’t wander.

Set up the card deck and board (2 min). Four colors of stickies (or four columns if you’re in Miro). Yellow for the story, blue for rules, green for examples, red for questions. Write the story — in the canonical “as a [persona], I want [action], so that [benefit]” format — on the yellow card at the top of the board.

Explore rules (5 min). Ask: what are the rules this story follows? What business rules, policies, constraints, edge-case handling shapes the behavior? Write each rule on a blue card and place under the story.

• “The user must be logged in.”
• “Orders over $1,000 require manager approval.”
• “Cancelled orders are retained for seven years.”

Don’t try to be comprehensive — aim for the rules that matter for this story, not every possible rule in the domain.

Explore examples (10 min). For each blue rule, ask: give me a concrete example. Specific, named values. Concrete users, concrete amounts, concrete states.

• Blue: “Orders over $1,000 require manager approval.”
• Green: “When Sally places a $1,200 order, the order is held for manager review.”
• Green: “When Sally places a $950 order, the order proceeds to fulfillment.”
• Green: “If the manager has been out for more than 24 hours, the order is escalated to the regional lead.”

The examples are the payload. They become acceptance criteria. A rule without an example is an abstraction that the team is guessing about — force the team to be concrete.

Capture questions (5 min). As rules and examples surface, questions will too. Anything the team can’t answer on the spot goes on a red card.

• “What if the manager delegates approval to a team lead? Does that count?”
• “Is the $1,000 threshold the total, including tax and shipping, or pre-tax?”
• “What happens if the currency is different — does $1,000 USD compare to €1,000 EUR?”

Red cards are not bad news. They are the session’s early-warning system. The team has explicitly surfaced the things it doesn’t know, which is massively more valuable than pretending it does.

Judge readiness (3 min). Step back. Count the red cards.

• Zero reds, rules have examples → ready. Story proceeds to sprint planning.
• Few reds, resolvable before sprint → nearly-ready. Product owner owns the questions; story is ready once they’re answered.
• Many reds, or reds at the core of the story → not ready. Park the story. Resolve the questions. Bring the story back to example mapping later.

This is the moment that makes the whole technique worth the time. Readiness is observed, not declared.

Worked example

A team runs example mapping on a story during backlog refinement:

Yellow card (the story):

As a registered user, I want to enroll in autopay for my loan, so that I don’t miss payments and can avoid late fees.

Blue cards (rules):

• Enrollment requires a valid bank account on file.
• Autopay draws on the loan’s payment due date.
• If the account has insufficient funds, autopay retries once after 48 hours.
• A user can cancel autopay at any time; cancellation takes effect on the next un-drawn cycle.
• Users are notified 3 business days before each draw.

Green cards (examples, by rule):

Red cards (questions):

• “What if the user has multiple eligible bank accounts?” — the story implies one, but the user model supports multiple. Which account does autopay use? Selected at enrollment, or a default? If default, how is default set? (Product owner follow-up.)
• “What’s the behavior if the first draw fails and then the second retry also fails?” — no rule covers this case. Rule gap, not just a question. (Could be escalate to manual billing, could be cancel autopay, could be freeze the loan — the team doesn’t know.)
• “Do we send a notification when autopay fails?” — notification rule only covers pre-draw, not post-failure. (Rule gap.)

Readiness call: not ready. The first red card is resolvable before sprint (PO chooses the policy). The other two are rule gaps — the team has surfaced two behaviors the story didn’t specify, which would have caused mid-sprint rework if unnoticed. The PO takes both questions back to the business-side stakeholders, returns with answers, and the story re-enters refinement with four rules where there were five and examples for the new gap-filling rules.

Without example mapping, this story would almost certainly have been pulled into the sprint as “ready,” and the rule gaps would have been discovered on day 4 of the sprint, costing a day of rework and either a slipped story or a partial release.

Common failure modes

• Rules without examples. The team lists five blue cards and moves on, skipping the green step. Rules without concrete examples are abstractions the team is guessing about. Every blue needs at least one green — if it doesn’t, that’s a red.
• Examples without values. A green card that says “an order is approved” instead of “Sally’s $1,200 order is approved” isn’t concrete enough. The whole technique depends on specifics. Push for names and numbers.
• Afraid to raise red cards. Teams new to example mapping sometimes treat red cards as admissions of failure. They aren’t — they’re the session’s single most valuable output. Model raising reds early; celebrate them when they surface.
• Running example mapping without the three amigos. Engineers alone produce technically-satisfying rules that may not match business reality. Without a business-side participant, the session drifts toward implementation detail. Minimum viable: one engineer, one product/business, one testing/QA.
• Over-running the time-box. Example mapping is 25 minutes, not an hour. A session that runs 90 minutes has turned into a design session — useful, but no longer example mapping. If the story genuinely needs 90 minutes, that’s a readiness signal in itself.
• Using example mapping as a replacement for BDD three-amigos. The formats have different scopes. Example mapping is fast and story-scoped; three-amigos is slower and often feature-scoped. Use each for what it’s good at; don’t pretend one replaces the other.

References

In the playbook

• Event storming workshop — the product-level counterpart when scope is larger than a single story.
• 3.6 Specification — the BDD-heavy playbook chapter where example mapping’s output feeds acceptance criteria.
• Journey mapping — broader-scope alternative for customer-experience stories.
• Pre-mortem — pairs well with example mapping for architecturally risky stories; example mapping catches behavioral ambiguity, pre-mortem catches structural risk.

External references

• Matt Wynne, Introducing Example Mapping (Cucumber blog, 2015) — the canonical write-up.
• Matt Wynne and Aslak Hellesøy, The Cucumber Book: Behaviour-Driven Development for Testers and Developers, 2nd ed. (Pragmatic Bookshelf, 2017) — broader BDD context.
• Gojko Adzic, Specification by Example: How Successful Teams Deliver the Right Software (Manning, 2011) — the specification-by-example discipline example mapping operationalizes.
• Liz Keogh, Behaviour-Driven Development — related practitioner writing, especially on the three-amigos pattern that example mapping compresses.
• Cucumber.io — Community learning — workshop-ready materials for teams adopting BDD and example mapping together.