The GreenBox team has done good work. They Event Stormed and got the whole domain out of Maya’s head. The hotspots on the wall made it clear: subscriptions are the critical path – nothing else works without them.
Now they need to build something. And the first story on the board is: “Subscribe to a produce box.”
Sounds clear enough, right? That’s what they thought four weeks ago too, and it didn’t go well.
The story is too vague to build from. What does “subscribe” actually mean? What has to happen? What could go wrong? What does the customer see? Tom could start coding right now, but he’d be guessing – again – and the team knows where that leads.
They need a way to turn that vague story into something concrete before anyone opens an IDE.
What is Example Mapping?
Example Mapping is a structured conversation technique created by Matt Wynne. The idea is simple: get a small group together for a short, focused session, take a single user story, and break it apart until everyone agrees on what “done” looks like. What are the rules? What are the concrete examples? What can’t we answer yet?
By the end of the session, you know one of three things: the story is well-understood and ready to build, the story is too big and needs splitting, or there are too many unknowns and it needs more research first. All three are useful outcomes. The worst thing you can do with a vague story is start building it.
The technique uses four colours of index card (or sticky note, or virtual equivalent) to keep the conversation structured.
Four colours of card
Yellow is the story. One card. The thing you’re discussing.
Blue is for rules. These are the business rules, constraints, and acceptance criteria that govern how the story works. Each rule gets its own card.
Green is for examples. Concrete, specific instances that illustrate a rule. “If X happens, then Y.” These are the things that tell you what “done” looks like.
Red is for questions. Anything you can’t answer in the room. Unknowns, disagreements, things that need research or a decision from someone who isn’t here.
That’s it. Four colours, four purposes.
How to run one
The format is deliberately tight:
- Keep it short. Twenty-five minutes is a good starting point – long enough to explore a story properly, short enough to stay focused. Set a timer. If you haven’t finished, the story is too big or too unclear. That’s useful information.
- Small group. At minimum: someone who understands the business (product person or domain expert), someone who’ll build it (developer), and someone who’ll challenge the assumptions (often a tester or QA person, but anyone sceptical will do). Three to five people is ideal. More than that and it becomes a committee meeting.
- One story at a time. Don’t try to batch these. One story, one session.
- Write as you go. Someone states a rule, write it on a blue card. Someone gives an example, write it on a green card under that rule. Someone asks a question nobody can answer, write it on a red card.
The conversation flows naturally. Someone proposes a rule. Someone else challenges it with an example. Edge cases surface. Assumptions get exposed. The map grows organically.
The first session: “Subscribe to a produce box”
The GreenBox team gathers round a table. Maya, Tom, Priya, Jas, and Sam. Lee facilitates. Twenty-five minutes on the clock.
Lee places a yellow card in the middle of the table and writes on it: Subscribe to a produce box.
“This is the story we’re exploring,” Lee says. “Don’t try to define it yet. I want to start with concrete examples. Give me a specific scenario – a real person doing a real thing. What does subscribing actually look like?”
Starting with examples
Jas goes first: “Someone visits the site, picks a box, enters their card details, and they’re subscribed.”
Lee nods but pushes back gently. “That’s a good start, but it’s abstract. Which box? What price? The more concrete the example, the more useful it is. Abstract examples hide assumptions. Concrete examples expose them.”
Jas tries again: “OK. Sarah visits the site, picks a small box at $25 a week, enters her Visa ending in 4242, and gets a confirmation with a delivery date of Thursday 2nd April.”
“That’s an example,” Lee says. He writes it on a green card: Sarah chooses small box ($25/week), pays with Visa 4242 → subscription confirmed, first delivery Thursday 2 April. He places it next to the yellow card.
“See the difference? The first version could mean almost anything. Everyone in the room would picture something slightly different. The second version leaves no room for ambiguity. Everyone can see exactly what we’re building. That’s what we’re after – examples concrete enough that there’s a shared understanding of what ‘done’ looks like, with no gaps for assumptions to hide in.”
“Give me another one. What else could happen?”
Tom: “The card gets declined. Say Sarah enters an expired card.”
Green card: Sarah tries to subscribe with expired Visa → no subscription, asked to retry with a different card.
“What happens then?” Lee asks. “Does she lose her box choice? Start over from scratch?”
Maya: “No, she just re-enters payment details. The box choice stays.”
Lee writes that detail on the green card. “Good – that’s exactly the kind of thing that would have been a bug if nobody asked. Now, more scenarios. What about the timing side?”
Maya: “We deliver on Thursdays. If someone subscribes on Monday, they should get a box this Thursday. If they subscribe on Friday, it’s next Thursday. Oh, and Mrs Patterson hates beetroot even though she hasn’t told us – but that’s a substitution problem, not a subscription one.” She says it casually, almost as a throwaway. Nobody writes it down.
Lee pushes for concrete details again: “Which Monday? Which Friday? Give me dates.”
Maya: “If Sarah subscribes on Monday 30th March, she gets a box Thursday 2nd April. If she subscribes on Friday 3rd April, she gets a box Thursday 9th April.”
Two more green cards:
- Sarah subscribes Monday 30 March → first delivery Thursday 2 April
- Sarah subscribes Friday 3 April → first delivery Thursday 9 April
“Concrete dates, concrete outcomes,” Lee says. “No ambiguity about what we expect to happen.”
Context, action, outcome
Lee pauses and looks at the cards on the table. “These are good, but let me point out something. Every solid example has three parts: the context – what’s true before anything happens, the action – what someone does, and the outcome – what should be true afterwards. Let’s check ours.”
He picks up the first green card. “Sarah chooses small box, pays with Visa 4242, subscription confirmed, first delivery Thursday 2 April. Where’s the context?”
Silence.
“Exactly,” Lee says. “There’s a ton of implicit context hiding in this example. We’re assuming box sizes are available. We’re assuming the site is up. We’re assuming Sarah doesn’t already have a subscription. Most of that is fine – you don’t need to state the obvious. But some implicit context is dangerous because it hides assumptions the team hasn’t agreed on.”
He picks up one of the delivery date cards. “Sarah subscribes Monday 30 March, first delivery Thursday 2 April. What’s the context here?”
Tom: “Delivery day is Thursday.”
Maya: “And the minimum lead time is three days.”
Priya: “And there’s no public holiday that week.”
“Right,” Lee says. “The delivery day being Thursday isn’t stated anywhere on this card. Neither is the lead time. If someone reads this example in two weeks, they’ll have to guess why Monday means Thursday. Let’s make the context explicit.”
He rewrites the card:
Context: delivery day is Thursday, minimum lead time is 3 days. Sarah subscribes Monday 30 March. → First delivery Thursday 2 April.
“And the other one:”
Context: delivery day is Thursday, minimum lead time is 3 days. Sarah subscribes Friday 3 April. → First delivery Thursday 9 April.
“Now the examples are self-contained. Anyone can pick up this card and understand not just what happens but why. The context tells you the setup. The action tells you what the user does. The outcome tells you what the system should do. When you’re missing any of those three, you’ve got a gap.”
Priya starts rewriting some of the earlier cards without being asked. This is Priya at her best – she sees structure where others see conversation, and she can’t leave a sloppy card on the table. The payment one becomes: Context: Sarah has selected a small box ($25/week). She enters an expired Visa. → No subscription created, asked to retry. Box choice is preserved.
“Better,” Lee says. “See how the context – ‘she has already selected a box’ – makes the ‘box choice is preserved’ outcome make sense? Without it, that outcome is a non-sequitur.”
Not every example needs three paragraphs of context. Some are obvious. But the discipline of asking “what’s the context?” catches the assumptions that aren’t obvious – and those are the ones that become bugs.
“What about Wednesday?” Tom asks. “If someone subscribes at 11pm on Wednesday, do they make the cutoff?”
Maya hesitates. “I think so… but the farms need to have confirmed supply by then.” She looks uncertain.
Lee picks up a red card. “That’s a question we can’t answer right now.” He writes: Exact cutoff time for same-week delivery? and places it off to the side.
“Don’t worry about it,” he says. “Red cards are good. They’re things we’ve caught before they became bugs. We’ll come back to them.”
Questions and assumptions
Sam asks: “Can someone have two subscriptions? Like a small box to their place and a large one to their mum’s house?”
The room goes quiet. Maya hadn’t considered it.
Lee writes a red card: Multiple subscriptions per customer? Then he asks, “Is that something we need for the first version?”
Maya: “No. Definitely not for version one. We’re trying to prove the basic model works.”
“Good,” Lee says. “That’s a different story. Park it.” He moves the red card to a separate area of the table. “Anything we discover that isn’t part of this story goes over here. We’re not losing it – we’re recognising it belongs somewhere else.”
Jas: “What about cancellation? Can they cancel any time?”
Another red card: What’s the cancellation policy? Lee moves it to the parked area too. “That’s its own story. Important, but not this one.”
“What about 3D Secure?” Priya asks. “Some cards need that extra authentication step.”
Red card: How do we handle 3D Secure? This one stays with the story – it’s a technical detail that affects the subscription flow directly. Tom volunteers to research it and come back with an answer.
Generalising to rules
“OK,” Lee says. “We’ve got a good set of examples and questions. Now let’s look at what they have in common. What rules emerge from these scenarios?”
The team looks at the green cards spread across the table.
Maya sees it first: “There’s a box size choice. Small or large. That’s it for now.”
Lee writes a blue card: Customer must choose a box size. He arranges the size-related green cards underneath it.
“Now that we have the rule,” Lee says, “does it spark any new examples? What could go wrong with box size selection?”
Priya: “What if they don’t choose? What if they hit ‘subscribe’ without selecting a size?”
Green card: Sarah clicks subscribe without choosing a size → error, asked to choose.
Tom: “And can they change their mind later? Switch from small to large?”
Maya: “Yes, but not mid-week. It takes effect from the next delivery.”
Green card: Sarah switches from small ($25) to large ($45) on Monday → change takes effect Thursday.
Lee nods. “See what’s happening? The rule generates new examples, and the new examples constrain the rule. Now we know it’s not just ‘choose a size’ – it’s ‘must choose a size before subscribing, and can change it with notice.’”
Tom: “Payment has to work too. That’s clearly a rule – no valid payment, no subscription.”
Blue card: Payment must succeed before subscription is created. The payment green cards go underneath.
“Same thing,” Lee says. “What else can go wrong with payment?”
Sam: “What about when the weekly charge fails three weeks in? Card expired, insufficient funds?”
Maya: “Good question. First failed charge, we retry after 24 hours. Second failure, we email them. Third, we pause the subscription.”
Three new green cards go under the payment rule:
- Weekly charge fails once → retry after 24 hours
- Two failures → email customer to update payment
- Three failures → subscription paused automatically
Tom whistles. “That’s a lot more than ‘payment must succeed.’ We’d never have built that retry logic without this conversation.” He’s quiet for a moment. Something he assumed would be straightforward – payment works or it doesn’t – just turned into a state machine with five transitions. Twenty-five minutes ago, he would have built it wrong.
Jas: “And they need to know when their first box arrives. Every scenario involves a delivery date.”
Blue card: Customer sees their first delivery date after subscribing. The timing green cards go underneath.
Lee pushes again: “What constrains the delivery date? What’s the edge case?”
Sam: “Public holidays. What if Thursday is a public holiday?”
Maya: “We’d deliver Wednesday instead. Or Friday. Depends on the courier.”
Red card: How do public holidays affect delivery dates? That one needs more research.
“Notice what happened,” Lee says. “We didn’t start with rules and try to think of examples. We started with examples – concrete, specific scenarios – and the rules emerged naturally. Then we used the rules to find more examples, and those examples tightened the rules. It’s a loop. If you start with rules, you tend to stay abstract. If you start with examples, you stay grounded in reality – and the rules get sharper every time you go round.”
The map so far
The timer hasn’t gone off yet, but the team feels like they’ve covered the core shape of the story. Here’s what the table looks like:
Reading the map
Three rules, eleven examples, three questions still attached to the story, and two parked for other stories. That’s a rich map — much richer than the three rules and six examples they would have had if they’d stopped after the first pass.
Lee walks the team through what they’ve got. “The green cards are your shared understanding. Each one is a concrete scenario the whole team has agreed on. The blue cards are the rules — and notice how much sharper they got once we explored more examples. ‘Payment must succeed’ turned into a whole retry policy. ‘Choose a box size’ now includes what happens when you don’t choose, and when you change your mind. The red cards on the story need answers before you start — Tom’s researching 3D Secure, Maya needs to decide the cutoff time, and Sam’s looking into public holidays. And the parked red cards? Those are new stories for the backlog. You didn’t lose them — you just recognised they don’t belong here.”
This is the power of Example Mapping. A short while ago, “Subscribe to a produce box” was a single line on a board. Now the team has a shared, concrete understanding of what they’re building — the rules, the edge cases, the things they don’t yet know, and the scope they’ve deliberately excluded. Two new stories discovered (multiple subscriptions, cancellation policy) without anyone having to write a specification document.
Nobody had to guess. They just talked, and the cards captured the conversation.
The “too many red cards” signal
Here’s a rule of thumb: if you have more red cards (questions) than green cards (examples), the story isn’t ready to build.
Four red cards against six green cards is borderline. The GreenBox team decides to resolve the cutoff question and the 3D Secure question before starting work, and to treat multiple subscriptions and cancellation as separate stories.
If they’d had eight red cards and three green cards, that would be a clear signal: the team doesn’t understand this story well enough. Go away, answer the questions, and come back for another session.
This is one of the best things about Example Mapping. It doesn’t just help you understand a story – it tells you when you don’t understand it. It’s a readiness check disguised as a planning session.
Second session: “Pause a subscription”
The next story up is “Pause a subscription.” A customer is going on holiday and wants to skip a week or two.
This time the session goes more smoothly. The team has been through Event Storming and the first Example Map. They know the domain better. Maya is in the groove of stating rules explicitly instead of assuming everyone already knows them.
Yellow card: Pause a subscription.
Rule 1: Customer can pause for one or more weeks.
Maya: “They pick how many weeks to pause. Minimum is one week.”
Green cards:
- Pause for 1 week → skip one delivery
- Pause for 3 weeks → skip three deliveries
Rule 2: Customer is not charged for paused weeks.
“This seems obvious,” Sam says, “but let’s write it down.”
He’s right to. Making the obvious explicit is half the point.
Green cards:
- Paused 1 week on $25/week plan → save $25
- Paused 2 weeks on $45/week plan → save $90
Rule 3: Must pause at least 3 days before next delivery.
Maya: “We need lead time. If their delivery is Thursday, they can pause up to Monday. After that, the box is already being packed.”
Green cards:
- Pause on Monday for Thursday delivery → OK
- Pause on Wednesday for Thursday delivery → too late
“What about Tuesday?” Priya asks.
Maya: “That’s fine. Three days before Thursday is Monday. Tuesday is two days before. So… no, Tuesday is too late.”
“Actually,” Tom says, “Monday to Thursday is three days. Tuesday to Thursday is two. So Tuesday should be too late.”
They update the rule to be precise: pause must be requested at least three days before the delivery date.
Green card:
- Pause on Tuesday for Thursday delivery → too late
Two questions come up:
Red card: Is there a maximum pause length?
Maya: “I don’t think so? But maybe we should cap it at, say, twelve weeks. If someone pauses for six months, are they really a subscriber?”
Red card: Can they extend an existing pause?
Nobody’s sure. If someone paused for one week and then decides to extend to three, can they? Or do they have to wait for the pause to end and then pause again?
Here’s the map:
Three rules, seven examples, two questions. Much cleaner ratio than the first session. This story is nearly ready to build – just need to resolve those two questions.
Notice how much faster this session went. The team is developing a shared language. When Maya says “three days before delivery,” everyone knows what delivery day means, how the weekly cycle works, what the constraints are. That shared understanding from Event Storming is paying off.
From examples to shared understanding
Those green cards aren’t just documentation. They’re a shared definition of “done” – expressed in concrete scenarios with explicit context, clear actions, and unambiguous outcomes. Everyone who was in the room has the same picture of what they’re building.
“Context: active subscription, delivery day Thursday, minimum 3 days notice. Customer pauses on Monday for 1 week. → Next delivery skipped, no charge, resumes following week.” That’s not a vague acceptance criterion. It’s a specific, concrete scenario the whole team has agreed on.
Compare that to “the system should handle pausing gracefully.” One is a shared understanding. The other is a hope.
Why Example Mapping is the one you’ll use most
Event Storming is brilliant for understanding a whole domain. You might do it once at the start of a project, or when entering a new area.
Example Mapping is different. You do it before every story.
Every single one.
It’s a short conversation. It surfaces assumptions. It catches edge cases. It builds a shared understanding of what you’re building and what “done” looks like. And it tells you when a story isn’t ready.
The GreenBox team starts doing Example Maps before picking up each new story. Before Tom and Priya start building, they spend twenty-five minutes with Maya and Jas mapping it out. The red cards tell them what to resolve. The green cards tell them what to build. The blue cards tell them the rules to enforce.
Three weeks in, they’ve stopped finding surprises in code review. The arguments about scope have disappeared. When Priya finishes a story, it matches what Maya expected, because they agreed on the concrete examples before anyone wrote a line of code.
When to use it
Before every story. Seriously, every one.
Even the ones that seem obvious. Especially the ones that seem obvious. “Subscribe to a produce box” sounded obvious too, and it had four open questions lurking inside it.
If you only adopt one technique from this series, make it Example Mapping. Event Storming is for stepping back and seeing the big picture. Example Mapping is the daily discipline – the thing that turns understanding into implementation, one story at a time.
Twenty-five minutes. Four colours of card. It’s the cheapest investment you’ll make all week.
Tom sits in his car after the session and texts Sarah: “I just spent 25 minutes doing something I thought was pointless and it saved me a week of work.” Sarah replies: “You sound surprised that something other than coding was useful.” He puts the phone down without responding.
Now what?
The team has a table full of cards. Three rules, eleven examples, three questions to resolve. They have a shared understanding of what “subscribe to a produce box” means – concrete, unambiguous, agreed upon by everyone in the room.
But cards on a table aren’t software. And the team still doesn’t have a rhythm for turning this understanding into delivery. Tom wants to start coding immediately. Maya wants to know when the subscription system will be ready for pilot subscribers. Nobody has a shared answer to “what are we doing this fortnight?”
They need a delivery cadence – a rhythm that turns all this discovery into working software on a predictable schedule.
That’s next (coming 14 April).