Example Mapping
Example Mapping is fspec's structured discovery technique that ensures AI and humans align on requirements before writing specifications.
Example Mapping is a collaborative workshop technique originally developed by Matt Wynne at Cucumber Ltd. For an in-depth exploration of this practice, see the Example Mapping Introduction (opens in a new tab) on the Cucumber blog.
What is Example Mapping?
Example Mapping is a collaborative workshop technique originally developed by Matt Wynne at Cucumber Ltd. For an in-depth exploration of this practice and its origins, see the Example Mapping Introduction (opens in a new tab) on the Cucumber blog.
Example Mapping is a collaborative discovery workshop technique that uses colored cards to organize information:
- Yellow Cards - User story (the "why")
- Blue Cards - Business rules (the "what")
- Green Cards - Concrete examples (the "how")
- Red Cards - Questions (the "unknowns")
- Gray Cards - Assumptions (the "accepted risks")
- Purple Cards - Architecture notes and NFRs (the "technical context")
- Attachments - Supporting files (diagrams, mockups, documents)
Why Example Mapping?
Traditional requirements gathering fails with AI agents because:
- ❌ AI jumps to conclusions without asking questions
- ❌ Abstract requirements lead to misinterpretation
- ❌ No structure for collaborative clarification
- ❌ Ambiguities discovered too late (during implementation)
Example Mapping solves this by:
- ✅ Forcing concrete examples before abstractions
- ✅ Making questions explicit (red cards)
- ✅ Enabling human-AI collaboration
- ✅ Discovering ambiguities early
The Card Types
Yellow Cards - User Story
The user story provides context for the feature:
fspec set-user-story AUTH-001 \
--role "registered user" \
--action "log in with my credentials" \
--benefit "I can access my account"Blue Cards - Rules
Business rules that must be true:
fspec add-rule AUTH-001 "Email must be valid format"
fspec add-rule AUTH-001 "Password must be at least 8 characters"
fspec add-rule AUTH-001 "Failed login increments attempt counter"Green Cards - Examples
Concrete examples showing the rule in action:
fspec add-example AUTH-001 "user@example.com with password 'secret123' succeeds"
fspec add-example AUTH-001 "invalid-email fails validation"
fspec add-example AUTH-001 "3 failed attempts locks account"Red Cards - Questions
Unknowns that need human answers:
fspec add-question AUTH-001 "Should we support OAuth providers?"
fspec add-question AUTH-001 "What is the account lockout duration?"
fspec add-question AUTH-001 "Do we need 2FA support?"Gray Cards - Assumptions
Accepted risks or temporary decisions:
fspec add-assumption AUTH-001 "We assume email is unique identifier"
fspec add-assumption AUTH-001 "We assume passwords stored with bcrypt"Purple Cards - Architecture Notes
Technical context, NFRs, and dependencies:
fspec add-architecture-note AUTH-001 "Uses bcrypt for hashing, salt rounds = 10"
fspec add-architecture-note AUTH-001 "Performance: Login must complete within 2 seconds"
fspec add-architecture-note AUTH-001 "Depends on Redis for session storage"Attachments - Supporting Files
Diagrams, mockups, and documents:
fspec add-attachment AUTH-001 diagrams/auth-flow.png --description "Authentication flow"
fspec add-attachment AUTH-001 mockups/login-ui.png --description "Login page mockup"The Example Mapping Process
Step 1: Start with User Story
fspec set-user-story AUTH-001 \
--role "registered user" \
--action "log in with email and password" \
--benefit "I can access my account securely"Step 2: Add Rules (Yellow Cards)
Start with business rules:
fspec add-rule AUTH-001 "Email and password required"
fspec add-rule AUTH-001 "Valid credentials return session token"
fspec add-rule AUTH-001 "Invalid credentials return error"Step 3: Add Examples (Green Cards)
For each rule, add concrete examples:
fspec add-example AUTH-001 "user@example.com + 'pass123' → success"
fspec add-example AUTH-001 "user@example.com + wrong password → error"
fspec add-example AUTH-001 "nonexistent@example.com → error"Step 4: Ask Questions (Red Cards)
Identify unknowns:
fspec add-question AUTH-001 "Max login attempts before lockout?"
fspec add-question AUTH-001 "Password reset flow?"Step 5: Human Answers Questions
fspec answer-question AUTH-001 0 --answer "5 attempts, 15 minute lockout"
fspec answer-question AUTH-001 1 --answer "Send reset email with 1-hour token"Step 6: Add Assumptions if Needed
fspec add-assumption AUTH-001 "Email service is reliable (99.9% uptime)"Step 7: Generate Scenarios
Once all red cards answered:
fspec generate-scenarios AUTH-001This creates a Gherkin feature file with scenarios based on your examples.
Viewing the Example Map
fspec show-work-unit AUTH-001Output:
AUTH-001: User login feature
Status: specifying
Rules:
1. Email and password required
2. Valid credentials return session token
3. Invalid credentials return error
Examples:
1. user@example.com + 'pass123' → success
2. user@example.com + wrong password → error
3. nonexistent@example.com → error
Questions:
[0] Max login attempts before lockout?
Answer: 5 attempts, 15 minute lockout
[1] Password reset flow?
Answer: Send reset email with 1-hour token
Assumptions:
1. Email service is reliable (99.9% uptime)Best Practices
DO:
- ✅ Start with user story
- ✅ Use concrete examples (not abstractions)
- ✅ Ask questions early and often
- ✅ Answer all red cards before generating scenarios
- ✅ Keep examples simple and focused
DON'T:
- ❌ Skip straight to scenarios
- ❌ Leave questions unanswered
- ❌ Use vague examples ("user logs in successfully")
- ❌ Mix multiple rules in one example
Example Mapping with Claude Code
When using /fspec in Claude Code, Claude will:
- Prompt for user story
- Collaboratively build the example map
- Ask questions as red cards
- Wait for your answers before proceeding
- Generate scenarios once complete
Next Steps
- ACDD Methodology - See how Example Mapping fits into ACDD
- Quick Start - Try Example Mapping yourself
- Discovery Commands - Learn all Example Mapping commands