{
  "id": "page:library-example-mapping",
  "_kind": "Page",
  "_file": "wiki/library/example-mapping.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "title": "Example Mapping Methodology (Library)",
    "displayName": "Example Mapping Methodology (Library)",
    "slug": "library/example-mapping",
    "articlePath": "wiki/library/example-mapping.md",
    "article": "\n# Example Mapping Methodology\n\n**Creator**: Matt Wynne (Cucumber Ltd)\n**Year**: Modern BDD practice (2015)\n**Category**: Requirements / BDD / Testing\n**Process ID**: `methodologies/example-mapping`\n\n## Overview\n\nExample Mapping is a simple, collaborative workshop technique for exploring and understanding requirements before development. It uses a structured approach with colored cards to break down user stories into testable examples.\n\nThis methodology bridges the gap between high-level user stories and detailed acceptance criteria, making stories ready for test-driven development and BDD practices.\n\n## The Four Colors\n\nExample Mapping uses four colored cards to organize information:\n\n- **🔵 Blue Card** - **User Story** (one per session)\n  - The feature or requirement being mapped\n  - Typically in \"As a [role], I want [feature], so that [benefit]\" format\n\n- **🟡 Yellow Cards** - **Rules/Acceptance Criteria**\n  - Business rules that apply to the story\n  - Constraints and validation logic\n  - What makes the story \"done\"\n\n- **🟢 Green Cards** - **Examples**\n  - Concrete scenarios illustrating each rule\n  - Given-When-Then format\n  - Happy paths, edge cases, and error cases\n\n- **🔴 Red Cards** - **Questions**\n  - Unknowns that need clarification\n  - Assumptions to validate\n  - Risks and dependencies\n\n## Key Principles\n\n1. **25-Minute Timebox**: If mapping takes longer, the story is probably too big\n2. **Conversation Over Documentation**: Collaborative exploration is key\n3. **Outside-In**: Start with story → identify rules → illustrate with examples\n4. **Ready Indicator**: Story is ready when questions are resolved and examples cover all rules\n\n## Process Flow\n\n### 1. Story Analysis (Blue Card)\n- Parse and understand the user story\n- Identify persona, feature, and benefit\n- Assess complexity and scope\n- Determine if splitting is needed\n\n### 2. Rule Extraction (Yellow Cards)\n- Identify business rules and acceptance criteria\n- Categorize rules (validation, business logic, constraints, etc.)\n- Prioritize must-have vs. nice-to-have rules\n- Consider edge cases and error handling\n\n### 3. Example Generation (Green Cards)\n- Create concrete examples for each rule\n- Cover happy paths, edge cases, and error scenarios\n- Use specific, realistic data\n- Ensure all rules have example coverage\n\n### 4. Question Identification (Red Cards)\n- Capture unknowns and assumptions\n- Identify technical and business questions\n- Note dependencies and risks\n- Prioritize blocking questions\n\n### 5. Gherkin Generation\n- Convert examples to Given-When-Then scenarios\n- Create scenario outlines for data-driven tests\n- Generate complete .feature files\n- Add appropriate tags (@smoke, @regression, etc.)\n\n### 6. Readiness Assessment\n- Verify all questions are resolved\n- Confirm complete rule coverage\n- Check if within timebox\n- Determine if story needs splitting\n- Issue final ready/not-ready decision\n\n## Usage\n\n### Basic Example\n\n```javascript\nimport { process } from './example-mapping.js';\n\nconst result = await process({\n  userStory: `As a customer, I want to search for products by name,\n              so that I can quickly find what I'm looking for`,\n  timeboxMinutes: 25,\n  sessionMode: 'collaborative'\n}, ctx);\n\nconsole.log(`Story Ready: ${result.isReady}`);\nconsole.log(`Rules: ${result.ruleCount}`);\nconsole.log(`Examples: ${result.exampleCount}`);\nconsole.log(`Questions: ${result.unresolvedQuestions} unresolved`);\nconsole.log(`Gherkin Scenarios: ${result.scenarioCount}`);\n```\n\n### With Existing Context\n\n```javascript\nconst result = await process({\n  userStory: `As a user, I want to reset my password via email,\n              so that I can regain access to my account`,\n  timeboxMinutes: 25,\n  sessionMode: 'collaborative',\n  existingContext: {\n    existingFeatures: ['email service', 'user authentication'],\n    securityPolicies: ['password complexity rules', 'rate limiting'],\n    relatedStories: ['user registration', 'email verification']\n  },\n  stakeholders: [\n    { role: 'product-owner', name: 'Alice' },\n    { role: 'security-lead', name: 'Bob' },\n    { role: 'developer', name: 'Charlie' }\n  ]\n}, ctx);\n```\n\n### Inputs\n\n| Field | Type | Required | Default | Description |\n|-------|------|----------|---------|-------------|\n| `userStory` | string | ✅ Yes | - | The user story to map |\n| `timeboxMinutes` | number | No | 25 | Session time limit |\n| `sessionMode` | string | No | 'collaborative' | 'collaborative', 'solo', or 'async' |\n| `existingContext` | object | No | null | Domain knowledge, related stories |\n| `stakeholders` | array | No | [] | Stakeholder information for questions |\n\n### Outputs\n\n```javascript\n{\n  success: true,\n  sessionDurationMinutes: 22,\n  withinTimebox: true,\n  story: {\n    original: \"As a...\",\n    analysis: { complexityScore: 5, scope: {...}, ... }\n  },\n  rules: [\n    { id: 'rule-1', description: '...', category: 'validation', ... }\n  ],\n  ruleCount: 4,\n  examples: [\n    { id: 'ex-1', title: '...', type: 'happy-path', given: [...], when: '...', then: [...] }\n  ],\n  exampleCount: 12,\n  questions: [\n    { id: 'q-1', question: '...', type: 'business', priority: 'high', blocking: true }\n  ],\n  questionCount: 3,\n  unresolvedQuestions: 1,\n  gherkinScenarios: [\n    { id: 'sc-1', name: '...', type: 'scenario', steps: [...], tags: ['@smoke'] }\n  ],\n  scenarioCount: 8,\n  coverageCheck: [...],\n  readiness: {\n    isReady: true,\n    readinessScore: 92,\n    criteria: { questionsResolved: true, completeCoverage: true, ... },\n    recommendations: [...]\n  },\n  isReady: true,\n  artifacts: {\n    storyAnalysis: 'artifacts/example-mapping/story-analysis.json',\n    rules: 'artifacts/example-mapping/rules.md',\n    examples: 'artifacts/example-mapping/examples.json',\n    questions: 'artifacts/example-mapping/questions.md',\n    gherkin: 'artifacts/example-mapping/scenarios.feature',\n    readinessReport: 'artifacts/example-mapping/readiness-report.md',\n    summary: 'artifacts/example-mapping/summary.json'\n  }\n}\n```\n\n## Integration Points\n\n### Perfect Precursor to Other Methodologies\n\n1. **Spec-Driven Development**\n   - Example Mapping outputs feed directly into specification creation\n   - Gherkin scenarios become executable specifications\n   - Rules become acceptance criteria in SPECIFICATION.md\n\n2. **TDD/ATDD**\n   - Examples drive test creation\n   - Gherkin scenarios become acceptance tests\n   - Red-Green-Refactor cycle uses examples as test cases\n\n3. **BDD/Specification by Example**\n   - Example Mapping is the workshop phase\n   - Outputs are ready for Cucumber/SpecFlow/Behave\n   - Scenarios are executable documentation\n\n4. **Agile/Scrum**\n   - Use in Sprint Planning or backlog refinement\n   - Helps with story estimation\n   - Identifies stories that need splitting\n\n5. **GSD Execution**\n   - Map examples before implementation planning\n   - Use readiness assessment to gate development\n   - Integrate with phase discussions\n\n## Success Criteria\n\nA successful Example Mapping session produces:\n\n- ✅ Clear understanding of the story scope\n- ✅ 3-8 business rules identified\n- ✅ Multiple examples per rule (happy path + edge cases)\n- ✅ All critical questions answered or documented\n- ✅ Complete Gherkin scenarios ready for automation\n- ✅ Session completed within timebox (usually 25 minutes)\n- ✅ Team consensus on story readiness\n\n## Signs a Story Needs Splitting\n\nIf Example Mapping reveals:\n\n- ❌ More than 8 rules\n- ❌ Session exceeds timebox significantly\n- ❌ Too many unknowns and red cards\n- ❌ Multiple distinct features in one story\n- ❌ Complexity score above 8/10\n- ❌ Unable to reach consensus\n\n→ **Split the story** and map each piece separately\n\n## Best Practices\n\n### Do's\n- ✅ Keep sessions timeboxed (25 minutes)\n- ✅ Use concrete, specific examples (not abstract)\n- ✅ Include multiple perspectives (product, dev, test)\n- ✅ Capture questions immediately (don't debate endlessly)\n- ✅ Focus on understanding, not perfect documentation\n- ✅ Split stories that exceed timebox\n\n### Don'ts\n- ❌ Don't skip the workshop and do it alone\n- ❌ Don't try to answer all questions in session\n- ❌ Don't write full Gherkin during the workshop\n- ❌ Don't map multiple stories in one session\n- ❌ Don't force stories that don't fit\n\n## Example Session Output\n\n### User Story\n> As a customer, I want to apply discount codes at checkout, so that I can save money on my purchase\n\n### Rules (Yellow Cards)\n1. ✅ Valid codes reduce order total by code percentage\n2. ✅ Expired codes are rejected with error message\n3. ✅ One code per order (no stacking)\n4. ✅ Minimum order value may apply\n5. ✅ Code is case-insensitive\n\n### Examples (Green Cards)\n\n**Rule 1: Valid code reduces total**\n- Given: Cart total is $100, code \"SAVE20\" gives 20% off\n- When: Customer applies \"SAVE20\"\n- Then: New total is $80, discount shows $20 off\n\n**Rule 2: Expired code rejected**\n- Given: Code \"OLD10\" expired yesterday\n- When: Customer applies \"OLD10\"\n- Then: Error shown \"Code expired\", total unchanged\n\n**Rule 3: No stacking codes**\n- Given: Code \"FIRST15\" already applied\n- When: Customer tries to apply \"SECOND10\"\n- Then: Error shown \"Only one code allowed\", original code remains\n\n### Questions (Red Cards)\n1. ❓ What happens if code brings total below $0? (blocking)\n2. ❓ Do codes apply to shipping costs? (high priority)\n3. ❓ Can codes be used with sale items? (medium priority)\n\n### Gherkin Output\n\n```gherkin\nFeature: Discount Code Application\n  As a customer\n  I want to apply discount codes at checkout\n  So that I can save money on my purchase\n\nBackground:\n  Given I am on the checkout page\n  And my cart contains items\n\nScenario: Apply valid discount code\n  Given my cart total is $100.00\n  When I enter discount code \"SAVE20\"\n  And I click \"Apply\"\n  Then my new total should be $80.00\n  And I should see \"Discount: -$20.00\"\n\nScenario: Reject expired discount code\n  Given discount code \"OLD10\" expired on \"2025-01-01\"\n  When I enter discount code \"OLD10\"\n  And I click \"Apply\"\n  Then I should see error \"This discount code has expired\"\n  And my cart total should remain unchanged\n\nScenario: Prevent stacking multiple codes\n  Given I have applied discount code \"FIRST15\"\n  When I enter discount code \"SECOND10\"\n  And I click \"Apply\"\n  Then I should see error \"Only one discount code allowed per order\"\n  And discount code \"FIRST15\" should remain applied\n```\n\n## References\n\n### Original Sources\n- [Cucumber Blog: Example Mapping Introduction](https://cucumber.io/blog/bdd/example-mapping-introduction/)\n- [Matt Wynne's Example Mapping Video](https://www.youtube.com/watch?v=VwvrGfWmG_U)\n- [Example Mapping Webinar](https://cucumber.io/blog/bdd/example-mapping-webinar/)\n\n### Related Reading\n- [BDD and Example Mapping](https://cucumber.io/blog/bdd/)\n- [Specification by Example (book) - Gojko Adzic](https://gojko.net/books/specification-by-example/)\n- [The BDD Books - Discovery, Formulation, Automation](https://bddbooks.com/)\n\n### Community Resources\n- [Example Mapping Template](https://cucumber.io/blog/example-mapping/)\n- [Example Mapping Facilitation Guide](https://johnfergusonsmart.com/example-mapping-bdd/)\n\n## License\n\nThis methodology implementation is part of the Babysitter SDK orchestration framework.\n\nCreator credit: Matt Wynne and Cucumber Ltd for the Example Mapping technique.\n",
    "documents": [
      "specialization:example-mapping"
    ]
  },
  "outgoingEdges": [
    {
      "from": "page:library-example-mapping",
      "to": "specialization:example-mapping",
      "kind": "documents"
    }
  ],
  "incomingEdges": [
    {
      "from": "page:index",
      "to": "page:library-example-mapping",
      "kind": "contains_page"
    }
  ]
}