Acceptance Criteria and Example Mapping: Clarifying Rules with Examples

Version note: This post is conceptual; Example Mapping follows Matt Wynne's "Introducing Example Mapping", published on the Cucumber blog on December 8, 2015, and the Definition of Done follows the 2020 Scrum Guide.

Guess First

In the previous post the cards of the first release were settled. The pink row holds two cards whose rules are still open questions: "Institutional discount" and "Partial shipment choice". Hakan's long-awaited answer finally arrives by email: "Institutional orders have a minimum of 20 copies, and the institutional discount is 10 percent." Emre reads it and relaxes: "Two if statements. Half a day."

Before reading on, try to answer these three orders using Hakan's sentence. A school wants 12 copies of the grade 5 mathematics book and 7 of the science book: can the order go through? A library wants 20 copies of a story book that is already on a 25 percent campaign: is the discount 25 percent, 10 percent, or both stacked? Someone buys 3 copies of a book listed at 84.95 TL and the discounted line total comes out at 229.365 TL: should the invoice say 229.36 or 229.37? Which of these could you answer with certainty from the email?

Acceptance Criteria: A Story's Definition of "Done"

Acceptance criteria are the conditions a story must meet for the Product Owner to accept it. They are exactly the confirmation leg of the card, conversation, confirmation trio from post 03: the form of the agreement reached in conversation that can later be checked with "does this work?". Two properties set them apart from everything else: they belong to that story only, and they describe behaviour, not implementation.

In practice they come in two forms. The rule-based form lists the rules the story must satisfy as short, checkable sentences: "An institutional order with fewer than 20 copies in total cannot be placed." The scenario-based form describes the rule through a concrete situation: "When the institution orders 19 copies of the mathematics book, the order is rejected and the institution is told that 19 copies is below the minimum." The first is short and scannable; the second leaves less room for misunderstanding because the numbers and the outcome are on the table. A good story usually has both: the rule stands like a heading and the examples beneath it make it precise. In this post we find the rules and examples through conversation; in post 07 we turn the examples into the Given-When-Then form, that is, into Gherkin.

The test for a testable criterion is simple: two people looking at the same system should agree on "met" or "not met". "The discount is calculated correctly" fails this test because it doesn't say what "correct" is. "40 copies of a book listed at 250 TL give a line total of 9,000 TL" passes. The vague word hunt from the first post applies here too: words like "appropriate", "correct" and "if needed" are warning signs in acceptance criteria as well.

Acceptance Criteria, Definition of Done and Definition of Ready

These three concepts get mixed up in backlog conversations. In the Scrum series post "The Increment and the Definition of Done" we put the difference in one sentence: acceptance criteria are specific to a single item, while the Definition of Done is the quality standard for the whole Increment. At Bookstore, "a campaign discount and the institutional discount do not stack" concerns only the discount story; it is an acceptance criterion. "The code was reviewed, the tests are green in the CI pipeline, new endpoints are covered by authorization tests" is the same for every story; it belongs to the Definition of Done. The test is easy: if an item repeats word for word in every story, it is in the wrong place.

The Definition of Ready, on the other hand, is not in the Scrum Guide; it is a checklist many teams add themselves. In the Scrum series post "The Product Backlog and the Product Goal" we discussed the risk of that list turning into a gatekeeper: a rule like "a story without complete acceptance criteria cannot enter the sprint" looks orderly on paper, but in practice it pushes the conversation before the sprint and onto one person, usually the Product Owner. So instead of a readiness checklist, Selin's team picks a short habit: before sprint planning, a twenty-five-minute Example Mapping session for every story whose rules are unclear.

Example Mapping: Cards in Four Colours

Example Mapping is a simple technique for structuring the conversation around a story, introduced in 2015 by Matt Wynne, the lead of the Cucumber project. The materials are just cards in four colours. The yellow card is the story itself and sits at the top of the table. Blue cards are the story's rules, the acceptance criteria already known. Green cards are concrete examples lined up under each rule. Red cards are questions nobody in the room can answer right now.

For participants Wynne recommends at least the "three amigos": a developer, someone bringing a testing perspective and a product person. Bookstore has no dedicated tester; in these sessions Ayşe deliberately wears the testing hat and looks at every rule asking "where does this break?". The suggested time for a well-understood story is about 25 minutes. Running over is information: the story is either too big or still too uncertain.

Two small habits keep the technique fast. First, examples are not written in Given-When-Then form during the session; Wynne suggests giving them short names in the style of Friends episode titles, starting with "the one where...". At Bookstore that becomes "the one with exactly 20 copies", "the one with the campaign book". Second, an example whose outcome nobody knows is not an example but a question; it goes on a red card, not a green one.

A Session: The "Institutional Discount" Card

Tuesday morning. Selin, Emre and Ayşe are at the table; Hakan joins for the first ten minutes. Selin puts the yellow card down: "Institutional discount: the purchasing officer sees the total with the institutional discount applied." Two blue cards come out of Hakan's email beneath it: "An order must have at least 20 copies" and "The institutional discount is 10 percent."

Ayşe starts writing examples for the first blue card and has to stop at the very first one. "20 copies of one book, accepted. What about 19 mathematics and 1 science?" Hakan answers: the minimum looks at the order's total quantity, not at each book. Ayşe makes the card precise: "An order contains at least 20 copies in total." Three green cards go under it: "the one with 19 mathematics and 1 science: accepted", "the one with 10 and 10: accepted", "the one with 12 and 7: 19 copies, rejected". Emre adds another: is a rejected institution told how far below the limit it is? Hakan says "yes, otherwise they call us", and that becomes an example too.

At the second blue card the campaign question comes up. Story books are on a 25 percent campaign during the summer; what happens if a library wants 20 copies of one? Hakan answers in the session: discounts do not stack, the larger one applies. That answer lands on the table as a new blue card and gets two green cards: "the one with 40 copies of the 250 TL mathematics book: line 9,000 TL, 10 percent discount" and "the one with 20 copies of the 120 TL campaign story book: line 1,800 TL, 25 percent discount".

After Hakan leaves, Emre puts the third order from Guess First on the table: 3 copies of the 84.95 TL science book. The list total is 254.85 TL, 229.365 TL after the 10 percent discount. How is it rounded to the cent, per line or on the order total? Nobody in the room knows; this is a red card, and it belongs to Bookstore accounting, because they are the ones who export invoices to the ERP system. Emre writes on the card who to ask and by when.

At the end of twenty-five minutes the table looks like this:

Accounting's answer arrives on Thursday: the ERP rounds every line separately and rounds a half cent up. The red card becomes a new blue card with the example "the one with 3 copies of the science book: line 229.37 TL" beneath it. Had this answer arrived mid-sprint, Emre's code would most likely have used .NET's default rounding, banker's rounding, produced 229.36, and the difference would have surfaced on the first invoice, in the school's accounting office.

The Second Card: "Partial Shipment Choice"

The second yellow card produces a very different table. The story: when stock is insufficient, the institution chooses between a partial shipment and waiting. The first blue card is easy: the institution makes its choice when it places the order. Then the cards multiply. Do the missing books go in a second shipment? Who pays shipping for the second one? Is the invoice for what was shipped or for the whole order? If a line is split across three campuses and stock covers only one, what happens? Is stock checked when the order is placed or when the warehouse picks it?

Fifteen minutes later there are seven blue and four red cards on the table. Two of the red ones belong to the warehouse, one to Bookstore accounting and one to corporate sales. One of Ayşe's examples connects back to the first card: if the first parcel of a partial shipment holds 12 copies, does it break the minimum of 20? Selin can answer this in the session: the minimum looks at the order, not the shipment. That is not a new rule but an example that clarifies the scope of the rule on the first card.

The real finding at this table is not any single card but the shape of the table. The first story had three rules with a few examples under each. Here the rules outnumber the examples and almost every rule has a question next to it.

At the End of the Session: Ready, Split or Investigate?

Wynne gives a few hints for reading the table, and they are enough to decide. Lots of red cards show that the team still has a lot to learn about the story. Lots of blue cards suggest the story is big and should be split. Lots of examples piled under a single rule mean that rule is really several rules. When time is up, the team decides with a thumb vote whether the story is ready for development; small questions may stay open.

For the "Institutional discount" card the vote is quick: three thumbs up. One red card was left, but its answer would not change the size of the story, and its owner and date were known. The story is ready.

For "Partial shipment choice" the answer is no, and two separate decisions come out. The first is to split. Of the axes from post 04, rule variations helps here: one of the institution's two options, "one shipment when everything is ready", touches none of the warehouse or accounting questions. The warehouse had already asked for the "one order, one shipment" rule in the workshop. Only this slice stays in Release 1: if stock is short for any book, the order waits as a whole and leaves in a single shipment. The second is to investigate. The "ship the missing ones later" slice depends on answers from the warehouse and accounting; the team does not open a spike for it, because the unknown is a business rule, not a technical one. Selin sets up a half-hour meeting with the warehouse manager and accounting, and the card moves down to the second release.

This decision also changes the story map: in the pink row, the "Partial shipment choice" card gives way to "If stock is short, the order waits as a whole". Selin lets Nevin Hanım know too; knowing in advance which option will not exist in September beats a surprise for the school.

From the Map to the Back of the Card

An example map that stays in the session is forgotten two days later. The team moves the map to the back of the "Institutional discount" story, its acceptance criteria, like this: each blue card becomes a rule sentence, each green card an example line under that rule.

• An institutional order contains at least 20 copies in total. Examples: 19 + 1 accepted; 10 + 10 accepted; 12 + 7 rejected, and the institution is told the order has 19 copies.
• The institutional discount is 10 percent off the list price. Example: 40 copies of a 250 TL book, line total 9,000 TL.
• A campaign discount and the institutional discount do not stack; the larger one applies. Example: 20 copies of a 120 TL book on a 25 percent campaign, line total 1,800 TL.
• Each line total is rounded to the cent separately, a half cent up. Example: 3 copies of an 84.95 TL book, line total 229.37 TL (source: Bookstore accounting, Thursday).

This list is both rule-based and scenario-based: the rule sentence says what holds, the numbers say exactly what is expected. Because list price, quantity and expected result are known, every line can become a test directly; we will do that with Gherkin in post 07 and with Reqnroll in post 08.

In Production

Use real numbers in examples. Writing 84.95 TL and 3 copies instead of "a book, a few copies" is what surfaced the rounding question. If you have real prices and quantities from the catalog or from last September's orders, use them.

Never leave a red card without an owner. Every question leaves the room with who will answer it and by when; when the answer comes, the card turns into a blue or green card, and that change is written into the acceptance criteria. The person who answered and the date go next to it; this is the lightest form of the traceability we discussed in the first post.

Keep the content of the map, not its photo. Nobody opens a photo of the cards on the wall a week later. Write the rules and examples into the story itself; when a new example turns up, say from an unexpected school order in production, it is added there.

Keep sessions short and frequent. Twenty-five-minute sessions spread over the week before sprint planning catch more questions than a single two-hour refinement meeting, and they wear nobody out.

Common Pitfalls

The first pitfall is writing acceptance criteria as a list of UI steps: "The user clicks New Order, pastes the list, presses Calculate and sees the total in the top right corner." These sentences state no rule; they become wrong when the button is renamed and still look right when the rule changes. Criteria should describe behaviour: which order gets which total.

The second pitfall is discovering edge cases mid-sprint. Had the rounding question not come up in the session, it would have surfaced during a test on day seven of the sprint, and the story would have stalled while Emre waited for accounting. The real job of Example Mapping is to make questions like this visible before the sprint.

The third is turning the session into the Product Owner's monologue. If Selin reads the rules and the team nods, the result is a presentation, not a map. The developer and the testing perspective should write the examples; their "what about this case?" is what finds the edge of a rule.

The fourth is turning every possibility into an example. A rule with forty green cards is either several rules or the team is testing the same boundary with different numbers. To clarify a rule, both sides of the boundary and one interesting case are usually enough.

The fifth is turning Example Mapping into a new item on the Definition of Ready. A rule like "a story without a map cannot enter the sprint" turns a short conversation habit back into a gate. Some stories have rules so clear they need no map.

A Small Experiment

★☆☆ Read the acceptance criteria of the next story in your backlog. Mark every item: does it describe behaviour or a UI step? Turn the UI steps into rule sentences.

★★☆ Run a twenty-five-minute Example Mapping session for one story; if you have no cards, four colours of sticky notes or a digital whiteboard will do. At the end, count the blue, green and red cards and use the hints in this post to decide whether the story is ready, should be split or needs investigation.

★★★ Find a rule question that surfaced mid-sprint in your team's last three sprints. Draw a retrospective example map for that story: under which rule would the question have appeared as a red card, and who could have answered it? Take it to your next retrospective.

With Example Mapping we clarified the behaviour of the institutional order with rules and examples. But we also heard sentences in the session that fit on no card: "check a 1,000-line list without making people wait", "the system must not go down in September", "one school must not see another school's order". These are not rules of a single story but expectations about the quality of the system. In the next post we move to non-functional requirements: the ISO/IEC 25010:2023 quality model, making "it should be fast" measurable, and where these requirements should be recorded.