Example Mapping: Breaking Down User Stories Before Writing Tests

Most planning meetings produce agreement on intent and disagreement on detail. "Users should be able to place orders" — everyone nods. But what happens when a user exceeds their credit limit? When the cart is empty? When a required field is missing? When you are halfway through checkout and the session expires?

The disagreements surface in code review, in QA, or in production. Example Mapping brings them to the surface in a 25-minute conversation before a single line of code is written.

The Technique

Matt Wynne developed Example Mapping at Cucumber Ltd as a lightweight alternative to lengthy refinement sessions. It uses physical index cards in four colors, one card per idea:

• Yellow — the user story (one card per session, sits at the top)
• Blue — business rules that govern the story
• Green — concrete examples that illustrate each rule
• Red — questions and unknowns that nobody in the room can answer

You arrange them on a table or digital board:

[YELLOW: Place an Order]

[BLUE: Must have items]         [GREEN: Empty cart → rejected with message]
                                [GREEN: One item → accepted]

[BLUE: Credit limit applies]    [GREEN: $499 order, $500 limit → accepted]
                                [GREEN: $501 order, $500 limit → held for review]
                                [RED: What about orders exactly at the limit?]

[BLUE: Price must be positive]  [GREEN: Item with $0 price → ???]
                                [RED: Can we sell free items? Ask Sarah.]

[RED: What happens to reserved inventory when order is held?]

At the end of 25 minutes you have either a story that is ready to develop (few red cards, concrete examples for every rule) or a story that is not ready (too many red cards, rules still fuzzy). Both outcomes are valuable — finding the unreadiness now costs nothing. Finding it during implementation costs a sprint.

Running the Session

Who should be in the room: one developer, one tester, one product person. Exactly three people. More than three and the session becomes a committee. The "three amigos" format is intentional.

Materials: index cards or a digital board (Miro, FigJam, Mural all work). If remote, prepare a template with four colored columns.

Time: 25 minutes per story. Set a timer. The constraint matters — it forces focus and prevents the session from becoming a design discussion.

Step 1: Write the Story Card (2 minutes)

The product person writes the user story on a yellow card and reads it aloud:

As a warehouse operator, I want to place orders for customers, so that inventory can be allocated and fulfillment can begin.

One sentence is enough. The Examples Mapping session will reveal the details.

Step 2: Identify Business Rules (5 minutes)

The team brainstorms the rules that govern this story. Each rule goes on a blue card. Rules are declarative: "Orders must contain at least one item." Not procedural: "When user submits, check items array length."

Typical rules for an order story:

• Orders must contain at least one item
• Item prices must be positive
• Customers must have an active account
• Orders over the credit limit are held for review
• Tax is calculated based on the customer's billing address

Go fast. Write every rule you think of. You will refine later.

Step 3: Illustrate Rules with Examples (15 minutes)

For each rule, write concrete examples on green cards. This is the heart of the session.

An example is not a description — it is a specific instance: "Given customer Acme Corp with a $500 credit limit, when they place a $501 order, then the order is held for review with status 'PENDING_REVIEW'."

The specificity is the point. Vague rules hide disagreement. Concrete examples expose it.

For the credit limit rule, you might write:

Green: $499 order, $500 limit → PENDING (accepted)
Green: $500 order, $500 limit → PENDING (accepted — boundary)
Green: $501 order, $500 limit → PENDING_REVIEW (held)
Green: Customer has no credit limit set → ???

That last one becomes a red card — nobody in the room knows the answer. That is fine. Write it down and move on.

Step 4: Capture Questions (throughout)

Whenever anyone says "it depends", "I'm not sure", or "we'd have to check" — write a red card. Do not try to resolve it in the session. The goal is to surface unknowns, not answer them.

After the session, red cards become action items: "Sarah will confirm by Thursday whether orders can be placed with zero credit limit." The developer does not start implementing until the answers come back.

Step 5: Review the Map (3 minutes)

Look at the map as a whole:

• Few red cards, clear examples for every rule: story is ready. Move to writing Gherkin.
• Many red cards: story is not ready. Schedule a follow-up once questions are answered.
• A rule with no examples: the rule is vague. Either write an example or delete the rule.
• An example with no rule: you've discovered an implicit rule. Write the blue card.

From Examples to Gherkin

The green cards translate almost directly to Gherkin scenarios. Each card is a scenario or a row in a Scenario Outline.

From the examples above:

Feature: Placing Orders

  Rule: Orders must contain at least one item

    Scenario: Empty cart is rejected
      Given customer "Acme Corp" has an active account
      When they attempt to place an order with no items
      Then the order is rejected with the message "An order must contain at least one item"

  Rule: Orders over the credit limit are held for review

    Scenario Outline: Credit limit determines order status
      Given customer "Acme Corp" has a credit limit of <credit_limit>
      When they place an order totalling <order_total>
      Then the order status is "<status>"

      Examples:
        | credit_limit | order_total | status         |
        | $500         | $499        | Pending        |
        | $500         | $500        | Pending        |
        | $500         | $501        | Held for Review |

Notice that the Rule: keyword in Gherkin maps directly to your blue cards. The Serenity BDD report will group scenarios under rules, which mirrors the Example Map exactly. Stakeholders reading the report see the same structure the team used to design the story.

Common Mistakes in Example Mapping Sessions

Inviting too many people. Example Mapping works because it creates a focused conversation between three perspectives: technical (developer), quality (tester), and product (business). Add a manager, architect, and second developer and you get a committee. Keep it to three.

Trying to solve red cards in the session. When a question comes up, write the red card and move on. The instinct is to debate until you reach consensus. Resist it. Unresolved questions are information — they tell you the story isn't ready. Forcing a decision in the room often produces the wrong answer because the right person isn't there.

Writing rules that are really implementation details. "The API validates the items array before persisting" is not a business rule — it is implementation. A business rule is "orders must contain at least one item." Keep rules at the business level. Implementation is the developer's job.

Writing examples that are too abstract. "Order is accepted when credit limit is sufficient" is not an example — it's a restatement of the rule. An example has specific values: "$499 order, $500 limit". The specificity forces precision and often reveals edge cases that the abstract statement hides.

Skipping the session when the story "seems simple." Simple stories are rarely simple. The session surfaces assumptions. The shorter the conversation, the more likely you are agreeing on different things. Do the session even for stories you think you understand.

Letting the timer run indefinitely. The 25-minute limit is a feature. If the story cannot be mapped in 25 minutes, it is too large or too unclear. Split it or do another round of discovery. A story that takes 90 minutes to map will take weeks to implement correctly.

Remote Example Mapping

In-person Example Mapping is easier because physical cards on a table create shared focus. Remote works well with the right tools.

FigJam or Miro: Create four sticky-note colors matching the card types. Pre-populate the yellow card with the story before the session. Use a shared timer visible to all participants.

Retool or Notion: Some teams build simple databases where each card type is a record type. Less visual but easier to export to Jira or Linear later.

Key remote adjustments:

• Assign a facilitator whose only job is to write cards as people speak. In person, anyone can grab a card. Remote, the writing bottleneck slows the session.
• Share screen on the board, not on slides. The board is the artifact.
• Use the chat for questions during the session so the facilitator can batch them into red cards without interrupting flow.

Connecting Example Mapping to Your Development Workflow

Example Mapping fits naturally into a sprint cycle:

1. Monday refinement: Run Example Mapping for stories entering the sprint
2. Tuesday: Resolve red cards from Monday (answers from stakeholders)
3. Wednesday: Convert green cards to Gherkin, walk through with the team
4. Thursday–Friday: Implement — the Gherkin is already the specification

The Gherkin written from the map goes directly into the repository as feature files. Step definitions are written alongside implementation. By the time the story is "done," the living documentation is also done — it was written before the first line of code.

Conclusion

Example Mapping is the smallest useful conversation you can have before starting work. Twenty-five minutes, three people, four card colors. The output is either a story with concrete, testable examples — ready to become Gherkin scenarios — or a map full of red question cards that tells you clearly: this story is not ready to build.

Either outcome is better than discovering the ambiguity in code review. The technique pays for itself on the first story that turns out to be two stories. After a few sessions, teams report that implementation goes faster not because the coding changed but because the thinking happened earlier, when changing your mind is free.