Purpose
When business rules need to become precise, it ties language, example, and test together. It sorts work by value, risk, and delivery ability. The result is captured as an Example Table and Acceptance Tests.
Agile Workshop method
Specification by Example
Makes business rules jointly understandable, formalisable, and later automatable through concrete examples.
Specification by Example connects Discovery, Formulation, and Automation. Business, development, and test roles clarify rules with realistic examples, express them in domain language, and keep executable specifications aligned with system behaviour.
Which concrete examples show that the business rule is correctly, completely, and testably understood?
- Participants
- 3-6
- Time
- 60-90 min pro Feature
Discovery clarifies rules and examples, Formulation makes them readable and executable, and Automation checks system behaviour.
Discover
Explore rules with examples
Build shared understanding of the rule, boundaries, and open questions.
Formulate
Write readable specifications
Express selected examples with context, event, and expected outcome.
Automate
Connect examples to the system
Integrate executable examples as fast, reliable delivery feedback.
Maintain
Keep living specifications current
Synchronise rules, examples, automation, and system behaviour when change occurs.
Update examples with every rule change; version specification and automation with product code.
A good fit when
Useful for behaviour-rich software requirements and rules with boundaries. Technical quality attributes need additional measurable criteria.
Ideal for
- Refinement
- BDD introduction
- Complex business rules
Not good for
- Pure UI polish tasks without logic
Outputs
Example map and rule set
Business rules, typical cases, boundaries, counter-examples, and open questions.
Living executable specification
Domain-language examples with automation status and shared versioning.
Rule-example specification
Fictional worked example
Each row connects a business rule to one concrete example and remaining clarification.
| Example | Business rule | Given: context | When: event | Then: outcome | Open question or boundary |
|---|---|---|---|---|---|
| Cancellation exactly 24 hours beforeBoundary example | Cancellation is free until and including 24 hours before start. | Appointment starts 20 June at 10:00; €120 paid. | Customer cancels 19 June at 10:00. | €120 is refunded in full; confirmation shows €0 fee. | Which timezone determines start and cancellation time? |
1. Business rule
- Cancellation exactly 24 hours before
- Cancellation is free until and including 24 hours before start.
2. Given: context
- Cancellation exactly 24 hours before
- Appointment starts 20 June at 10:00; €120 paid.
3. When: event
- Cancellation exactly 24 hours before
- Customer cancels 19 June at 10:00.
4. Then: outcome
- Cancellation exactly 24 hours before
- €120 is refunded in full; confirmation shows €0 fee.
5. Open question or boundary
- Cancellation exactly 24 hours before
- Which timezone determines start and cancellation time?
One example illustrates one rule. Resolve questions before Formulation or defer them visibly.
First step
Start with the core question: Which concrete examples show that the business rule is correctly, completely, and testably understood?
Good to do first
Deep dive
How it works
It formulates behavior through concrete examples and uses them as a shared reference for understanding and validation. This turns description into a verifiable specification that all sides can read and check against the same cases.
In detail
Specification by Example, popularized by people such as Gojko Adzic, adds concrete examples to user stories and later uses them as executable tests. The examples are created collaboratively and use the domain's own vocabulary. They connect discovery, refinement, and engineering without a seam.
Facilitation
Choose examples that cover both rules and edge cases. Avoid example numbers that create bias, such as only round numbers.
The method guide walks execution through 4 phases, timing, 4 pitfalls, and clear stop criteria.
Open method guideYour perspective
Does this method help with your work?
Your feedback helps shape the next improvements to methodatlas.
Sources and topics
Artifact templates
Specification by Example: WorksheetPlan Specification by Example with real scope, suitable roles, and a clear decision objective.markdown
Specification by Example: WorksheetPlan Specification by Example with real scope, suitable roles, and a clear decision objective.
markdownspecification-by-example-working-template.md
Plan Specification by Example with real scope, suitable roles, and a clear decision objective.
Specification by Example: Worksheet
Question
To be confirmed
Desired outcome
To be confirmed
Scope
Establish and review the practice Time: 25–45 minutes of Discovery per small story; Formulation and Automation follow
Complete this worksheet on paper or in your own document during the work.
Preparation for this scope
Method setup
- Materials: Story or rule, real cases, four-colour Example Mapping cards, domain vocabulary, feature file, and test access.
- Roles: Product/domain expert · developer · tester · optional facilitator
- Advance information: Select a small change, gather known rules and incidents, and invite a domain decision maker.
- Overall time needed: 25–45 minutes of Discovery per small story; Formulation and Automation follow
- Setup: Keep story, rules, examples, and questions separate; formulate Gherkin only after shared Discovery.
Prepare for the work steps
Discover: Explore rules with examples
- Small story or business change
- Domain expert, developer, and tester
- Known rules and incidents
Formulate: Write readable specifications
- Example map
- Shared domain vocabulary
- Resolved questions
Automate: Connect examples to the system
- Agreed specification
- Test access and data
- Product code
Maintain: Keep living specifications current
- Executable specification
- Test results
- New business decisions
Rule-example specification
| Example | Rule | Initial context | Event | Observable outcome | Question · boundary |
|---|---|---|---|---|---|
| Cancellation exactly 24 hours before |
- Cancellation exactly 24 hours before: Boundary example
Describe business behaviour; omit UI and implementation detail.
Cucumber: Behaviour-Driven Development
Discover: Explore rules with examples
Expected artifact: Example map
Rules · examples · questions · scope
Entry:
...
- Does each example illustrate one rule?
Formulate: Write readable specifications
Expected artifact: Executable specification
Rule · Example · Given · When · Then
Entry:
...
- Can a domain expert review behaviour without implementation knowledge?
Automate: Connect examples to the system
Expected artifact: Automated examples
Specification · test binding · result
Entry:
...
- Does failure explain a business-relevant reason?
Maintain: Keep living specifications current
Expected artifact: Living documentation
Current rules · examples · test status
Entry:
...
- Does every green example still describe relevant behaviour?
Open questions and next steps
...
Method guide: https://methodatlas.meierhoff-systems.de/en/methods/specification-by-example/run-sheet
Alternatives and neighbors
Fitting alternatives with decision guidance, followed by other related methods.
Agile
Example Mapping
Instead of Specification by Example, choose Example Mapping when you want to use concrete examples as a bridge between domain language and acceptance criteria.
Agile
Story Splitting
Splits stories that are too large into smaller testable slices while keeping value, dependencies, and interfaces in view.
Agile
Three Amigos
Brings business, development, and testing together before implementation to clarify a story's examples, rules, and edge cases.
Agile
Story Points
Moves backlog, sprint work, and team flow toward a concrete result through "choose reference stories", "define the scale", and "interpret velocity only within the team".
Agile
Ideal Days
Moves backlog, sprint work, and team flow toward a concrete result through "explain the ideal day unit", "calibrate with a reference item", and "do not confuse it with calendar days".
Agile
Planning Poker
Compares stories relatively, surfaces knowledge gaps, and produces a shared estimate with traceable assumptions.
Constraints and origin
MediumWorkshop60-90 min pro Feature
Profile
- Method form
- Workshop method
- Participants
- 3-6
- Time
- 60-90 min pro Feature
- Maturity
- Canonical
- Origin
- Gojko Adzic
Next up: Acceptance Criteria Workshop