example-mapping

Breaks stories and specs into rules, concrete examples, and open questions using four-colour example mapping.

1|Updated May 21, 2026
One-click install
npx skills add https://github.com/vnovakovits/claude-skills --skill example-mapping-vnovakovits
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: example-mapping
Source: https://github.com/vnovakovits/claude-skills/tree/main/plugins/engineering-practices/skills/example-mapping
Command: npx skills add https://github.com/vnovakovits/claude-skills --skill example-mapping-vnovakovits

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Abstract requirements discussions and written specs often hide under-specified rules, missing examples, and unanswered questions. This Skill applies Matt Wynne's Example Mapping technique to turn a story or spec into a four-colour map (yellow story, blue rules, green examples, red questions) whose shape immediately reveals what is missing. ## Core Features & Use Cases - Discovery Mode: Run a 25-minute three-amigos session that maps a story into rules, concrete examples, and parked questions before development starts. - Audit Mode: Map an already-written spec to verify every documented example against its rule, derive missing boundary cases, and expose rules that are asserted but never illustrated. - Shape Diagnostics: Read the map's imbalances — empty rule columns, orphaned examples, red-heavy maps — to decide whether a story is ready to build or a spec is ready to sign off. - Use Case: Before refining a shipping-quote feature, map its rules (carrier preference, tie-breaks, exclusions) with concrete priced examples; the resulting red cards become the review agenda and the green cards become the acceptance-test inventory. ## Quick Start Ask Claude to run an example mapping session on your story or spec, for example: "Use example mapping to break this story into rules, concrete examples, and open questions."

Frequently Asked Questions about example-mapping

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run an example mapping session for a user story?▼

Timebox about 25 minutes with product, dev, and test present. Start with the yellow story card and existing acceptance criteria as blue rule cards, then alternate asking for examples of each rule and asking which rule each example illustrates, parking anything unresolved as a red question card.

What is example mapping in agile requirements refinement?▼

Example mapping is Matt Wynne's four-colour discovery technique: a yellow story card, blue rule cards, green concrete example cards hung under each rule, and red question cards. The shape of the finished map diagnoses whether the story is ready to build.

Can example mapping be used to review an existing specification document?▼

Yes, audit mode maps a written spec by extracting its rules as blue cards, placing and verifying every documented example under a rule, and deriving missing NEW examples for boundaries, ties, and empty sets. The red column becomes the review agenda.

When should I not start development based on an example map?▼

Do not start when the map is red-heavy, when rules have no green example cards, or when the story has more than about six rules. A red-heavy map means open questions dominate, and many rules means the story should be split first.

How do example mapping cards become acceptance tests?▼

Each green example card converts into one acceptance test, typically formulated as Given/When/Then scenarios in behavior-driven development. Red cards become the review agenda, and blue cards form the spec's rule list.