Skip to content
Tutorials Center
My learning

Topics

Lesson 6 of 37 ยท BDD Concepts and Gherkin

The Three Amigos and Example Mapping

Run effective discovery sessions: who the three amigos are, how example mapping uses rules, examples and questions, and how to turn the outcome into Gherkin scenarios.

Discovery is where BDD earns its keep, and the most common format for it is a short, focused meeting of three perspectives: business, development and testing. They are called the three amigos (the number is a guideline; sometimes there are four or five people). Their job is to leave the meeting with a shared understanding of one user story, written as a handful of concrete examples.

This lesson describes the meeting, introduces the card-based technique called example mapping, and shows how to move from the map to Gherkin.

The three perspectives

Perspective Asks Brings
Business (product owner, analyst, domain expert) "What problem are we solving, and what does success look like?" The rules and the reason behind them
Development "How would this work, and what is hard about it?" Technical feasibility, hidden complexity
Testing "What if...? What could go wrong?" Edge cases, unusual inputs, risks

The value is not that each person does their own job; it is that they find each other's blind spots. The product owner learns a rule is expensive to build. The developer learns a rule has a loophole. The tester learns the intent behind a feature before testing it.

Keep sessions short: 25 to 30 minutes per story is plenty. If a story needs more, it is probably too big and should be split.

Example mapping

Example mapping, created by Matt Wynne, uses four colors of index cards (or sticky notes, or a shared whiteboard):

The four cards of example mapping

Story The one feature in discussion
Rules Business rules and criteria
Examples Concrete cases per rule
Questions Things nobody can answer yet

Yellow on top, blue below it, green under each blue, red on the side.

1 / 2

The layout is a small tree: the yellow story card at the top, a row of blue rule cards below it, and green example cards under the rule they illustrate. Red question cards collect anything that cannot be answered in the room; someone takes each one away to find the answer.

flowchart TB
    S["Story: Free shipping"]
    S --> R1["Rule: 50 dollars or more ships free"]
    S --> R2["Rule: smaller orders pay 5 dollars"]
    R1 --> E1["Example: 75 dollars, shipping 0"]
    R1 --> E2["Example: exactly 50 dollars, shipping 0"]
    R2 --> E3["Example: 49.99 dollars, shipping 5"]
    S --> Q1["Question: do discounts count towards the 50?"]

The map after ten minutes. The red question blocks readiness.

How to run the session

  1. Write the story on a yellow card and read it aloud.
  2. Pick one rule at a time. Write it on a blue card. Ask: "Can you give me an example?"
  3. Write each example on a green card under its rule. Use real numbers and real names ("Maria orders 75 dollars of books"), never "a customer with a valid order".
  4. When a rule produces many examples, the rule is probably two rules. Split it.
  5. Park unknowns on red cards. Do not argue for ten minutes about something nobody present can decide.
  6. Check the room's confidence at the end (a thumbs vote works). The story is ready to build when there are few or no red cards and a reasonable number of examples.

A useful smell test: a story with more than about five rules or ten examples is too big; a story with no examples is not understood.

A map as data

The stand-in below models the cards and evaluates whether the story is ready: it counts rules without examples, lists open questions and prints the verdict. Add an example under the second rule, or remove the question, and the verdict changes.

Java Stand-in: example map and readiness check

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Turning the map into Gherkin

Each blue rule becomes a group of scenarios (or, in Gherkin 6+, a Rule: block), and each green card becomes one scenario. The mapping is mechanical, and a computer can do the typing. The next stand-in turns an example card of the form "name, amount, expected" into a scenario text. The generated text is not final prose (a human should polish the wording and drop duplicates), but the exercise shows how little translation is left once the examples are concrete.

Java Stand-in: from example cards to scenario text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Good facilitation habits

  • Invite everyone with a stake but keep the room small enough that everyone speaks.
  • Use real data. "A customer with a gold membership" hides the question what gold means; "Priya, gold member since 2022" does not.
  • Capture rules in the team's words. These words become the step vocabulary.
  • Do not design the UI in the meeting. Talk about what the user achieves, not which buttons they click. That distinction is the subject of the lesson on declarative scenarios.
  • Write down who owns each red card before the meeting ends.

Anti-patterns

  • The solo scribe. One person writes scenarios alone and "shows the team later". The shared understanding never forms.
  • Meeting after coding. If discovery happens after the code is written, examples merely justify what exists.
  • Rule soup. Twelve rules in one session means the story needs splitting.
  • Endless debate. If two people disagree for more than two minutes, write a red card and move on.

When the map is ready, the next step is formulation, the language of the next lesson: Gherkin syntax.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Who are the three amigos?

    The idea is to combine business, development and testing views to find each other's blind spots.
  2. 2. In example mapping, what does a red card hold?

    Red cards park unanswered questions so the session keeps moving; someone takes each one away.
  3. 3. A story has fifteen rules. What does this suggest?

    Many rules or examples indicate a large story; splitting it keeps sessions short and the work estimable.
  4. 4. Which example is best for a discovery session?

    Concrete names and numbers make the example testable and expose hidden questions.

Summary

  • The three amigos (business, development, testing) discover a story together before code is written.
  • Example mapping uses yellow story, blue rule, green example and red question cards.
  • A story is ready when rules have examples and questions are resolved; too many rules means split it.
  • Each green card becomes a scenario; each blue card becomes a group or a Rule:.
  • Use real names and numbers, and keep UI details out of the conversation.

Next: Gherkin Syntax