Specifying by Example

Workflow: Writing SBE specifications

1. Clarify the business goal. Ask what problem the feature solves and for whom. If the user provides a user story, extract the goal. If they provide raw requirements, ask "why are we building this?"

2. Identify rules. Extract the distinct business rules from the requirements. Each rule is a constraint or behavior the system must enforce. Name each rule explicitly.

3. Generate examples for each rule. For every rule, produce:

   • The happy path (main success scenario).
   • Key boundary conditions (edges where behavior changes).
   • Important negative cases (what the system should refuse). Use realistic data (real names, plausible amounts), not "foo"/"bar."

4. Write Gherkin scenarios. Convert each example into a Given-When-Then scenario following these rules:

   • Declarative, not imperative. Describe what happens, not UI steps. No CSS selectors, button names, or page navigation.
   • One behavior per scenario. Each scenario has exactly one When-Then pair.
   • Essential data only. Include only data that illustrates the rule. Omit incidental details (user IDs, timestamps, irrelevant fields).
   • Ubiquitous language. Use the same terms the business uses. No user_id, POST /api/orders, or status = 2.
   • Name the rule. Group scenarios under a Rule: keyword in Gherkin.

5. Use Scenario Outlines for boundary tables. When a rule has many input-output combinations, use a parameterized Scenario Outline with an Examples table instead of repeating similar scenarios.

6. Check for specification gaps. Are there rules with no examples? Examples with no clear rule? Unanswered questions? Surface these explicitly.

7. Organize by domain concept. Group feature files by business capability (e.g., specs/pricing/, specs/accounts/), not by sprint or ticket number.

Workflow: Reviewing SBE specifications

1. Read all scenarios in the feature file or specification document.
2. Check each scenario against these anti-patterns:

Anti-pattern	Symptom	Fix
Imperative scripts	Steps say "click," "type," "navigate"	Rewrite in declarative style
Multi-behavior scenarios	Multiple When-Then pairs	Split into one scenario per behavior
Incidental detail overload	Irrelevant data (user IDs, timestamps)	Strip to essential data only
Technical leakage	Steps reference APIs, HTTP codes, DB tables	Replace with business-language equivalents
Inconsistent vocabulary	Same concept called different names	Pick one term and use it everywhere
Scenario proliferation	Hundreds of trivially different scenarios	Use Scenario Outlines; push combinatorics to unit tests
Too abstract	"Given sufficient funds / When they withdraw / Then it succeeds"	Add concrete amounts and expected outcomes
UI-coupled specs	Scenarios break when the UI is redesigned	Automate against the API/service layer; use declarative language

3. Verify the specification covers happy path, boundaries, and negative cases for each rule.
4. Propose specific fixes with before/after Gherkin.

Quick example

Input: "Users get free shipping on orders over $75, otherwise $5.95 flat rate."

Output:

Feature: Shipping cost calculation

  Rule: Shipping is free for orders over $75; otherwise $5.95 flat rate

    Scenario Outline: Shipping cost based on order total
      Given an order with a subtotal of <subtotal>
      When the shopper proceeds to checkout
      Then the shipping charge is <shipping>

      Examples:
        | subtotal | shipping |
        | $50.00   | $5.95    |
        | $74.99   | $5.95    |
        | $75.00   | $0.00    |
        | $75.01   | $0.00    |
        | $150.00  | $0.00    |

The boundary ($75.00) is tested from both sides. The rule is stated in prose above the scenarios.

When NOT to apply SBE

Ask two questions before reaching for SBE:

1. Will a non-developer ever need to read or validate this specification? If only developers will care, use standard test frameworks.
2. Is there genuine ambiguity about what the system should do? If everyone already agrees, write a test and move on.

Skip SBE for: trivial CRUD, pure infrastructure/DevOps, throwaway prototypes, unit-level logic, algorithmically complex internals, and highly exploratory work.

A healthy ratio: SBE scenarios cover 10–20% of the test suite (high-value acceptance layer); unit and integration tests cover the remaining 80–90%.

Reference material

• Collaborative techniques: references/01-collaborative-techniques.md — Three Amigos, Example Mapping (with full walkthrough), Feature Mapping, discovery workshops, facilitation runbook
• Writing effective examples: references/02-writing-effective-examples.md — declarative style, single-behavior rule, detail calibration, ubiquitous language, worked examples
• Lifecycle and living documentation: references/03-lifecycle-and-living-documentation.md — core principles, the seven process patterns, living documentation curation
• Adoption, failure modes, and measurement: references/04-adoption-and-measurement.md — adoption failure modes, maturity model, story slicing with examples, spec-driven development, success metrics
• Glossary: references/05-glossary.md — SBE terminology reference