3.6 Specification
Before coding we need to make sure our design has enough fidelity. Specification is about adding those details, the happy paths as well as the failure scenarios, so we're confident moving into coding.
Moving into this activity you’ll need several design artifacts you built in previous chapters. Our definition of ready aligns us for success:
Before starting
Specification adds fidelity to our use cases so the finished product is a quality product. We explore variations on each scenario — happy paths and failure modes alike. What if credit authorization fails? The product isn’t in the warehouse? The customer adds a duplicate to the cart, or abandons it? Working through these scenarios with your team produces cleaner interfaces, more reliable code, and fewer defects caught in production.
We lean heavily on Behavior Driven Development (BDD) — a structured methodology that closely aligns requirements, engineering designs and business needs against the event maps and engineering models we built in 3.4 Tactical event storming and 3.5 Modeling. The companion blog post Delivering customer value with BDD explains why BDD is so important and how it fills gaps that other quality and test practices don’t. Read it before starting.
Guide to specification
Behavior Driven Development evolved from Test Driven Development. It actively involves both technical and business team members, shifting problem discovery to early in the software lifecycle.
Results are written in plain ubiquitous language everyone can understand. It relies on a structured “Given-When-Then” style (Gherkin format). This protects the value chain by aligning technical specifications with plain business speak, event maps and other artifacts.
The workshop uses the “three amigos” design conversation, which involves the customer. This surfaces disagreement or misalignment early, instead of waiting until user acceptance testing. When a product owner writes a scenario and a developer says, “but what if the product isn’t in stock?” — that’s a defect caught at essentially zero cost.
Inputs
- Technical models. Your technical design artifacts (marble diagrams and other drawings) sufficient for the current product increment.
- Your tactical event maps (for the current product increment).
- Supporting design artifacts, including capabilities and functions, key results, strategic event maps, and context map.
- A current sprint backlog, populated with your highest value feature and aligned with the product increment.
Process
The intent is exploration and discovery — a rich set of scenarios to round out your features, identify gaps, and document the requirements of a robust product increment.
The BDD process breaks down into three steps:
- Discovery — Stakeholders collaborate to explore features, asking “what should happen when…?” to uncover gaps.
- Formulation — The team writes “Given-When-Then” scenarios based on discovered examples.
- Automation — Engineers link specifications to code, verifying outcomes by making the specifications executable.
This activity focuses on Discovery and Formulation. Chapter 3.7 will align our artifacts so that we can achieve Automation (by linking specifications to your engineering test framework).
Feature discovery
For each feature in the backlog, a product engineer writes out the feature as described by the customer and business team members. Team members rely on the feature definition (from your business capabilities) and acceptance criteria (from your key results).
Each feature is written as a user story using the canonical format, “as a [persona], I want [action], so that [value/benefit].” This maintains focus on the key result we’re shooting for and makes it easier to link with executable code later.
Once the shell of a specification is confirmed among the three amigos, identify the primary scenario for the story — the base case, the main feature, typically the “blue sky” scenario:
FEATURE: Enroll in Autopay |
SCENARIO: Enroll in (new) autopay |
As the team runs into new scenarios, add them as brief alternative scenarios. Each will be expanded upon — but for now, capture all the positive, negative and alternate ideas that come up. Consider happy path, unhappy path and edge cases.
Be sure to define all the necessary scenarios that fully describe each feature: positive and negative cases, edge situations, error handling and alternative user paths.
For each scenario you’ll write the test cases that fulfill it. A given feature could have many different scenarios; each scenario has its own “Given-When-Then” statement defining how it will be verified.
Feature refinement and scenarios
Complete specifications define each feature with user story, acceptance criteria and test scenario:
- User story. The use case that describes your feature. Aligns with your previously defined personas and describes the business capabilities.
- Acceptance criteria. Your key results should form the foundation. These are verification criteria and specify business rules that must be met.
- Test scenario. A test case written in “Given-When-Then” Gherkin style. This is the test definition that explains how a scenario is ultimately verified. Using Gherkin syntax lets us link the specification to executable code later.
Every specification will clearly document its prerequisites, events describing the behavior and the expected outcome using the business’s ubiquitous language:
| Element | Structure | Purpose |
|---|---|---|
| Feature | FEATURE: <short title> | The feature gives context to the developer and puts guardrails on the scope. |
| Acceptance criteria | ACCEPTANCE CRITERIA: Define the conditions that must meet to be accepted by a user, a customer, or other system. | The conditions under which this feature is considered delivered. |
| Scenario | SCENARIO: <short title> | The test includes multiple scenarios using Gherkin syntax. Conjunctions AND, BUT and OR can also be used to provide additional details. |
Acceptance criteria should consider how the system works at both the detailed unit or component level and at the end-to-end assembly level. Define as many as needed. You can use this template as an example.
Iterate
Once the team has exhausted all possible scenarios, go back and refine any that weren’t fully described.
Running the workshop
Prepare
- Identify team participants. You’ll need your “three amigos” team — customer representation, engineering and a business expert. Typically product owner, lead engineer and either a business analyst or compliance/testing specialist. Don’t limit to three; bring in anyone with insight into features, user experience, business value and compliance needs.
- Brief the team. If your team isn’t familiar with BDD, have them read the companion Delivering customer value with BDD first.
- Give everyone time to prepare. Plenty of heads-up about the working session, circulate technical drawings and artifacts in advance, and make sure everyone can give their full attention.
Execute
Be sure your team is informed on how to collaborate in a BDD “three amigos” working session. While BDD specifically calls for the product owner, engineering lead and quality engineer (or business analyst), others are welcome. Balance the team to maximize collaboration and information flow, but don’t bog down the session.
Iterate through your backlog with the team members, with the three amigos actively driving the conversation:
- Feature discovery. From the backlog and design assets, review the specific feature and use case. Consult your feature OKRs (these define success criteria) and your tactical event maps (which provide fidelity on how the feature works).
- Feature refinement. Copy the feature into your specification template using the canonical “as a [persona], I want [action], so that [value]” format. As you go, features may change — one feature may fragment into several, or gaps may be discovered.
- Scenario formulation. For each feature, define test scenarios, acceptance criteria and new scenarios:
- Acceptance criteria definition. The whole team, often with product engineers leading by example, defines acceptance criteria.
- Test scenario definition. Product engineers write each test scenario in Gherkin syntax. (These are later linked to code to verify behavior — that’s why we use Gherkin.)
- Define new scenarios. Add new scenarios that capture all possible positive and negative outcomes.
- Review. Make sure feature, scenarios and test definition are complete. Think hard about positive and negative scenarios, not just the “blue sky” cases.
- Iterate. Repeat until the team is confident each feature in the product increment is complete.
Outputs
- Feature specifications. Clear human-readable test scripts (using the business’s ubiquitous language).
- Acceptance criteria. Verification rules tied back to your key results for each feature.
- Primary Gherkin scenarios. A “Given-When-Then” scenario for each feature’s blue-sky path, written at the feature level — deep enough to test against, shallow enough to elaborate further in the next chapter.
- Alternate and edge scenarios. Short Gherkin stubs alongside the primary scenario — happy & unhappy path, error handling, edge cases.
In the next chapter, 3.7 Elaboration, we’ll take these specifications from outline to depth — expanding each scenario across component- and assembly-level tests, live-linking every specification to its model so the two evolve together, and decomposing each feature into INVEST-shaped user stories ready for the sprint backlog.