The Workshop: Example Mapping

Twenty-five minutes, four colours of card, and a vague user story turns into something developers can actually build. Making Stories Concrete shows one team’s first run; this post is the reference you keep open the morning of yours.

Example Mapping

Example Mapping breaks a single user story into rules and concrete examples in twenty-five minutes, so the team knows whether the story is ready to build and what “done” actually means. Sometimes called specification by example at the sentence level, though specification by example usually implies a longer, heavier process. Sometimes confused with BDD (Behaviour-Driven Development – writing scenarios that double as executable tests) scenario writing – Example Mapping produces the material BDD scenarios are written from. Invented and named by Matt Wynne in 2015 as a pragmatic answer to “how do we make the Three Amigos – the developer / tester / business person trio that shapes a story before it’s built – conversation actually produce something?”

What’s It For

A developer picks up a story called “Subscriber can pause their box.” She reads the acceptance criteria, they look fine, she starts building. Three days in she hits a question: what happens to a box that’s already been packed when the pause takes effect? She asks the product owner. The product owner doesn’t know. The product owner asks the warehouse lead. The warehouse lead says “obviously the packed box goes out, we can’t unpack it,” and the developer’s first two days of work are now wrong.

This happens because the story looked simple. It wasn’t. There were three rules hiding inside it and at least one of them depended on operational knowledge nobody had written down. The conversation that would have caught it – a twenty-minute chat between the product owner, a developer, and someone from operations – would have happened before the sprint started if anyone had thought it was worth the time.

Example Mapping exists to make that conversation cheap enough that you always have it. The cards are the forcing function: you can’t hand-wave acceptance criteria when someone asks for a concrete example and you have to write it on a green card.

Reach for it when:

A story is about to enter a sprint and you want to know whether it’s actually ready
Developers and the product owner suspect they disagree about “done” but haven’t surfaced it
The story feels simple and you don’t trust the feeling
You need to decide whether a story should be split, built, or deferred for more discovery

What It’s Not For

Skip it when:

The story is genuinely trivial. A copy change, a feature flag flip, a config tweak. Just build it.
You don’t yet know what you’re building. Example Mapping assumes you have a story and drills into what it means; run Event Storming or User Story Mapping first to get the story in the first place.
The people who know the answers aren’t in the room. Without the product owner or the domain expert, the rules will get written but nobody will have the authority to say they’re right. Reschedule.

Stop a session that’s already started if:

Five minutes in and you can’t even seed a green card – the story is too vague to map; it needs discovery, not Example Mapping
The product owner is absent or checking their phone
Every rule is producing a red card – you’re not mapping, you’re discovering, and that’s a different session

Stopping early when the signal is clear is not failure. Forcing a doomed session to the 25-minute bell is.

Definitions & Background

Four card colours, each one belonging to a role in the conversation:

Yellow – the story. One card, at the top of the table, present for the whole session.
Blue – rules. Acceptance criteria phrased as business rules. “A subscriber can pause for up to eight weeks.”
Green – examples. Concrete scenarios that illustrate a rule. “A subscriber pauses on a Monday for two weeks. Her Wednesday box skips. Her next box is the following Wednesday.”
Red – questions. Things nobody in the room can answer. “What happens to a box that’s already been packed when the pause takes effect?”

Examples are primary; rules fall out of them. Wynne’s framing all the way through: someone offers a concrete example the product owner has in mind, the room abstracts a rule from it, then someone offers another example to test that rule. The next example either confirms the rule, refines it, or breaks it – and breaking it is fine. A broken rule is replaced with one or two sharper rules, or a red card if nobody knows. Teams who try to lead with rules produce neat-looking maps that miss the cases the business actually cares about.

The cards arrange themselves around the story: blue rules stretch left-to-right under the yellow story; green examples drop in columns under the rule they illustrate; red questions go off to the side where they can be counted at the end.

Inputs

One user story written on a yellow card at the top of the table. Participants who have read the story in advance are a small bonus, not a prerequisite.
Cards in four colours: yellow, blue, green, red. A table the participants can stand around – the layout grows: yellow story at the top, blue rules in a row underneath, green examples dropping in columns under each rule, red questions off to one side.
A 25-minute slot with no interruptions and the right people in the room (see Who’s Needed).

If the story isn’t yet defined enough to write on a card, run Event Storming or User Story Mapping first. Example Mapping doesn’t generate the story; it sharpens one you already have.

Outputs

What lands on the table at the end:

A clear verdict on the story – ready to build, ready with named assumptions, needs splitting, or blocked. State it out loud before anyone leaves the room.
Acceptance criteria as the blue rule cards, concrete enough to paste into the tracker.
Test scenarios as the green example cards, almost in BDD format already.
Open questions as red cards, each one a thing somebody needs to answer before the story enters a sprint.
Sibling stories, sometimes. When an example or a rule points to behaviour that doesn’t actually serve the user and outcome on the yellow card, capture it as a new yellow card parked next to the main one. This is a feature, not feature creep – discovering a sibling story mid-session is one of the most valuable ways scope gets split honestly.

Photograph the table layout from directly above before the cards come down – yellow at the top, blue rules in a row beneath it, green examples dropping in columns under each rule, red questions and any parked yellows off to the side.

These outputs feed straight into:

Sprint Planning – a story that’s been Example Mapped is ready for the capacity discussion. One that hasn’t shouldn’t be in the sprint conversation.
Decision Tables – when a rule has many conditions and the green cards become unmanageable, promote the rule to a decision table.
Assumption Mapping – red cards that can’t be answered by anyone in the room are often assumptions in disguise. They belong on the grid.

Who’s Needed

Three to five people, twenty-five minutes:

Facilitator. Runs the clock, asks for the next example, keeps people off implementation detours. Does not put cards on the table themselves except to demonstrate the colour convention at the start.
Product owner. Mandatory. They own the story and they’re the person who decides which rule applies when two participants disagree. If the product owner can’t attend, reschedule.
Developers. At least one, ideally two. They’ll catch the rules that are impossible or expensive to implement as written, and they benefit most from leaving with concrete tests in hand.
Tester or QA. Highly valuable if you have one. They will think of edge cases faster than anyone else in the room and they are the natural customer for the green cards.
Operations / support / domain expert. When the story touches a part of the system only one person really understands – the warehouse lead, the SRE who owns the cron that matters, the support agent who talks to the subscribers who hit this particular path – pull them in for this one session. They’ll save you a week.

Fewer than three and you don’t get enough friction between perspectives; more than five and the table becomes a meeting. Leave the rest of the team out – they’ll get the output through the acceptance criteria. Observers warp the conversation: if they care about the story, they should come as participants or read the output afterwards.

How To Run It

Phase	Duration	Cards	Key question
Explain the colours, read the story	2 min	Yellow	“What are we mapping?”
Seed the first rule	3 min	Blue + green	“What’s the most obvious rule? Give me an example.”
Explore the rules	15 min	Blue + green + red	“What happens if…?”
Assess readiness	5 min	Review all	“Is this ready to build?”
Total	25 minutes

Twenty-five minutes is the whole pattern. The time constraint is not cosmetic – if you can’t map the story in twenty-five minutes, the story is telling you something: it’s too big, too vague, or standing on unresolved questions. That signal is worth the entire session by itself.

Phase 1 – Seed the rules (3 minutes)

Read the yellow card aloud. All of it. Don’t paraphrase. If the story is two sentences long, read both sentences.

Then set the colour convention:

“Yellow is the story – it’s already on the table. Blue is for rules. A rule is an acceptance criterion phrased as a business rule: ‘a subscriber can pause for up to eight weeks.’ Green is for examples. An example is a concrete scenario: ‘A subscriber pauses on a Monday for two weeks, her Wednesday box skips.’ Red is for questions nobody in this room can answer right now. We’ll come back to those at the end.”

Now draw out the first rule. The product owner almost always has the obvious one:

“What’s the most basic rule – the thing that has to be true for this story to exist at all?”

Write it on a blue card. Place it below the yellow story. Then immediately:

“Can someone give me a concrete example of that rule? One specific scenario. Real names are fine.”

Write the example on a green card. Place it under the blue rule. You now have the shape of the session: yellow on top, blue in a row underneath, green in a column under each blue. Once the shape is visible, the room knows what to do.

Phase 2 – Explore the rules (15 minutes)

This is the core of the session. You now cycle: example, rule, example, red card, example, rule. The facilitator’s job is to keep the cycle moving by asking one of five questions over and over:

“Have you got a real example, and what rule does that example imply?”

“Can someone give me an example of that?”

“What happens if…?”

“Is that always true, or only sometimes?”

“Is that the same rule or a different rule?”

The first question is the most important and the easiest to skip. Examples drive rules, every time – start from a concrete example the product owner has in mind, abstract the rule from it, then offer another example to test the rule. The next example confirms the rule, refines it, or breaks it. A broken rule is replaced with one or two sharper rules, or a red card if nobody knows. Don’t let the team flip the order: when a rule shows up before an example, ask for the example before you write the rule down.

When an example or a candidate rule clearly belongs to a different story – it doesn’t serve the user or outcome on the yellow card – grab a yellow card and park it to the side. Don’t argue, don’t fold it in. Discovering a sibling story is a useful outcome, not a derailment, and the parked yellow becomes a candidate for its own session.

Place blue cards in a row. Place green cards in columns under their rule. Place red cards off to the right – a visible pile the team can count. Parked yellows go alongside the red pile; they’re a different signal but they live in the same margin.

Example Mapping works the same for infrastructure stories, with the SRE or pipeline owner taking the product owner’s seat. A rule might be “the pipeline rolls back on failed health checks” and an example “health check fails at 10:02, rollback begins at 10:03, service back on previous version by 10:05.” Same shape, different domain.

See Example Mapping: Making Stories Concrete for one team’s first run – including the moment a green card about an already-packed box turns into the red card that reshapes a week of work.

Phase 3 – Assess readiness (5 minutes)

Step back from the table. Look at the shape of the cards. The shape tells you the verdict.

Few blue cards, examples for each, no red cards – the story is well understood. Build it.
Many blue cards, examples for each, no red cards – the story is well understood but too big. Split it, probably by rule.
Red cards – the story has open questions. Each red card has two valid closures: get the answer, or make an explicit assumption you can defend and write it on the back of the card. The second closure is fine when the assumption is low-stakes or the team is willing to wear the consequence – but flag any high-stakes assumption (one where the wrong call breaks the plan) for Assumption Mapping before the sprint commits to building. Reds left as neither answered nor assumed mean the story isn’t ready.
Very few cards, session finished in twelve minutes – either the story really is trivial, or the team is being superficial. Probe once: “Is there any scenario we haven’t considered where this would behave differently?” If the answer is a confident no, you’re done.

State the verdict out loud. Someone – ideally the product owner – says the phrase: “This is ready to build”, “Ready with these assumptions”, “Needs splitting”, or “Blocked on these red cards”. Saying it out loud matters. It’s the commitment, and it’s what everyone remembers when someone later asks “wait, did we decide about this?”

What Can Go Wrong

The monologue. The product owner explains the story for ten minutes while everyone listens politely. Recovery: Interrupt and cash the monologue in for cards: “Stop there. Can someone capture what they just said as a rule on a blue card?” Forcing people to write cards forces them to be precise. Stop if: The monologue restarts after a second redirect. The story isn’t ready for Example Mapping – it needs a longer conversation first, and you should schedule one.

The rabbit hole. The team is fifteen minutes into debating one edge case. Recovery: Cash it in as a red card: “This is a great question. Let’s put it on red and keep moving. We’ll come back to it or take it offline.” Stop if: The same edge case keeps surfacing after two red cards. There’s a deeper unknown and you need a time-boxed investigation outside the room before another Example Mapping session will land.

The empty table. Nobody is writing cards. The conversation is circular. Recovery: The story is too vague. Ask a sharply concrete question: “What’s the simplest version of this story? One subscriber, one action, one outcome. What happens?” If that produces a green card, you have a seed. Stop if: The room genuinely can’t answer the simplest version. The story needs discovery, not mapping.

The premature solution. Developers start debating database schemas and API signatures. Recovery: “Great implementation thinking – hold it for when you start the story. Right now we’re still mapping what should happen.” Stop if: They can’t hold the distinction after three prompts. They’ll get more value from a design session.

The silent developer. A developer is in the room but not speaking, not writing, not asking for examples. Recovery: Name them and ask directly: “What’s the part of this story you’re most worried about implementing?” Worry is the fastest route to a red card. Stop if: They disengage completely. Something else is going on. Don’t try to fix it in-session.

The reverse map. The team writes blue cards directly from existing acceptance criteria and never generates green cards at all. Common in teams who’ve been running Example Mapping for six months – the ritual survives but the discovery has died. Recovery: Cover the blue cards with paper and ask for examples first. “Forget what we wrote. Tell me a real scenario for this story – a specific subscriber doing a specific thing on a specific Tuesday.” Once a green card lands, uncover the blues and see if they survive. Stop if: The room can’t produce a green card without seeing the rules. Example Mapping has degenerated into AC-rephrasing theatre; the story needs different discovery work first.

The committee verdict. The product owner defers to the developers when stating the readiness call. Recovery: Ask them directly: “Product owner, what do you want to do with this story?” The verdict is theirs to state. Stop if: They can’t or won’t make a call. The story isn’t owned. Don’t add it to the sprint until it is.

Next Steps

The session ends; the work begins.

Same day, the facilitator:

Photographs the card layout (one shot from above is enough – it’s only one table)
Transcribes the rules into the story’s acceptance criteria in the tracker
Transcribes the green cards as test scenarios, in BDD format if the team uses it
Writes the red cards into the tracker as open questions, each one with an assigned owner and a date

This week, the product owner:

Chases every red card to closure. Each red card needs one of two outcomes before the story enters a sprint: answered, or assumed-and-named. The product owner owns the choice. An answered red card folds back into the rules and examples; a named assumption gets written on the back of the card and goes into the story description so the team building it knows what they’re betting on. High-stakes assumptions – the kind where the wrong call breaks the plan – get tested via Assumption Mapping before the sprint commits. A red card that’s neither answered nor assumed is a production bug rehearsed.
States the verdict in writing. Update the story with “Ready to build”, “Needs splitting”, or “Blocked on [red cards]”. The verdict is the single most valuable artefact from the session.
Splits the story if it needs splitting. Each rule with its examples can often become its own story. Don’t defer the split until sprint planning – the shape is freshest now.
Walks the acceptance criteria back to the developers. They were in the room, but the transcribed criteria may look different from what they remember. Five minutes of “does this match what we decided?” prevents the slow drift between session and sprint.

Ongoing, the team:

Runs Example Mapping for every story before it enters a sprint. It takes twenty-five minutes and consistently prevents the mid-sprint “but I thought it meant…” conversations that cost days.
Tracks the red card rate. If it’s trending upward, stories are arriving at Example Mapping too raw – push for better discovery upstream.
Keeps the green cards visible during the sprint. They’re the tests, and having them on the team board keeps “done” honest.

Variants

Story Level (default). One user story about to enter a sprint, twenty-five minutes, three to five people. Output: rules, examples, questions, build/split/defer verdict. This is what most teams need, and the rest of this post describes it.

Epic Level. A cluster of related stories in an epic, ninety minutes, multiple passes with breaks between them. Output: a rough split of the epic into buildable stories. Reach for this when you’re trying to decide how to break up a large feature area; it’s really three or four Story Level sessions stacked together.

Remote. A Miro or Mural board with the four card colours pinned, video call for the conversation. Slightly slower (the rhythm of “write a card, place a card” is faster in person), but the structure transfers cleanly. Use one shared cursor: only the facilitator places cards, prompted by the team, to keep the layout legible.

Pre-sprint sweep. Run six or eight Story Level sessions back-to-back with a fifteen-minute break in the middle, twice a week. Three hours total but it surfaces the entire next sprint’s worth of unknowns in one sitting. Best for teams whose backlog grooming has slipped and stories arrive at planning underprepared.