3.7 Elaboration

Elaboration builds directly on the specifications you wrote in 3.6 Specification. Make sure your prior artifacts are complete and reachable — your team is going to be reading them constantly during the workshops:

Before starting

In 3.6 Specification we worked through the first two stages of Behavior Driven Development — Discovery and Formulation. We surfaced scenarios in three-amigos conversations and shaped them into Gherkin “Given-When-Then” statements. That gave us the outline of every feature in our product increment. Elaboration is where we move from outline to depth.

The specifications you write here are living documents. They will evolve, change and be added to. That’s why it’s so important to create a live link to the implementation — the code that will validate the specifications. As the specifications change, that live link preserves the value chain from customer desires all the way to delivered code.

This activity has three jobs. First, we expand each scenario across the levels at which the system is tested: component and assembly. A login feature has UX scenarios about what the customer sees and experiences. It also has assembly scenarios about which events fire, which commands route through which aggregates and what payload comes back. Both layers need specifications. Both layers need to be testable. Skipping a layer leaves a gap through which defects love to slip.

Second, we create a live link between every specification and the engineering model that implements it. Each Gherkin feature points back to a marble. Each marble points forward to a Gherkin feature. That bi-directional link is what makes our specifications living documents — when the spec changes, the marble updates with it, and vice versa.¹

Third, we decompose features into INVEST-shaped user stories that the engineering team can pull into a sprint and finish. This is the bridge from “design done” to “sprint backlog ready,” and it’s where elaboration earns its keep.

If any of the inputs above aren’t ready, go back and finish them. Walking into elaboration with thin source material guarantees thin output and a sprint that stalls.

Guide to elaboration

This is a workshop-driven activity, much like its predecessor. The three amigos drive the conversation, with the broader team brought in for the parts they own.

Inputs

• Feature specifications. Features and initial Gherkin scenarios from 3.6 Specification, with acceptance criteria.
• Engineering models. Marble and sequence diagrams from 3.5 Modeling.
• Tactical event maps. From 3.4 Tactical event storming.
• UX assets. Wireframes, screen mockups, design system references — anything that frames the customer-facing surface area.
• Sprint backlog. Your in-process backlog with the highest-value features for the current product increment.

Process

Elaboration unfolds in two passes. The first pass expands — taking each scenario and growing it across the testing levels and into a live link with the engineering model. The second pass decomposes — turning the elaborated features into INVEST-shaped user stories ready for the sprint.

Expand scenarios across testing levels

When we wrote scenarios in 3.6 Specification, we deliberately stayed at the level of the feature. That kept the conversation accessible to the customer and the business stakeholders. Now we go deeper.

Every scenario needs to be tested at more than one level. The feature “customer creates an account” doesn’t just need a UX test that drives a browser through the sign-up screen — it also needs an assembly test that confirms the right events fire, the right commands route to the right aggregates and the right data lands in the right context. Without both, you’re testing half the system.

Component-level testing

Component-level scenarios cover anything testable in isolation from the rest of the system — unit tests, UI/presentation tests against a single component, even small integration tests that mock collaborators.

These scenarios describe discrete behaviors, including the presentation scenarios that validate a customer’s journey through the user interface. They’re typically what your UX or QA engineer automates against the front-end. They live close to the wireframes and design assets, and they speak in the language of clicks, fields, screens and outcomes.

Here’s an example for a banking application — a customer creating a new user account:

A few patterns worth calling out, because they show up in every well-formed presentation-facing spec:

1. Clear business value. The “so that” clause names the outcome the customer cares about. If you can’t articulate the value, the feature probably isn’t ready.
2. Consistent language. The terms in the user story, the acceptance criteria and the scenario all match — and they match the ubiquitous language the team agreed on.
3. Specific examples. Concrete data tables (Sally Hanson, not “a customer”) make the spec testable and reveal edge cases you’d miss with abstract values.
4. “AND” for multiple steps. When a single Given, When or Then has more than one part, chain them with AND rather than collapsing into a single comma-separated sentence. The structure makes the test runner happy and humans happier.

Assembly-level testing

Assembly-level scenarios describe how components fit together — how events flow, how commands move through aggregates, what gets emitted, what payloads look like. These are the specs your back-end and integration tests verify. They live close to the marble diagrams and the tactical event maps.

Same business — different level:

Notice the differences. The actor is no longer a customer clicking buttons; it’s a system component reacting to an event. The Given is an inbound event with a correlation ID. The When describes a payload. The Then describes another event being emitted with a specific shape. This is the language the engineering model speaks.

A scenario that exists only at the presentation level is a scenario you can’t prove out below the UI. A scenario that exists only at the assembly level is a scenario the customer can’t see. You need both. You’ll need the end-to-end framing that stitches the two together — particularly for high-value paths that absolutely cannot break.

Link specifications to engineering models

This is the move that makes everything else worth the trouble.

Every feature maps to a marble or sequence diagram, and every scenario should be traceable to one or more marbles. The “Borrower is not a fraud and passes fraud checks” scenario above corresponds to marble 4.2, which expands the anti-fraud step in the prequalification flow.

Make the link explicit and bi-directional:

• From the engineering drawing, link to the specification — wherever the spec lives. Many teams keep the canonical spec in Jira, Confluence or a Git-tracked feature file. Pick one and link to it.
• From the specification, link back to the marble it implements.

Make the link mechanically enforceable — embed the feature ID in your marble’s filename so it’s easy to reconcile. Depending on your stack you’ll have different options. A .feature file can embed the feature-ID-based name along with a marble hash, enabling a CI check to detect if a marble is missing or changed. Put a mechanism in place to prevent “link rot” or uncaught changes from cascading into defects. This is even easier if you’re using Jira and Confluence because of their persistent links and automation hooks.²

There are different ways to implement live links. I diagram my marbles in Miro and visually connect them. Each gets a name based on its Jira ticket number. That number becomes the unifier. It shows up in the .feature file, it shows up in Confluence when I reference the Jira ticket. I can programmatically create a link to the marble from Jira, Confluence or from the CLI and .feature file — all I need is the name.

That bi-directional link is the live wire that keeps the value chain intact. When the spec changes — and it will — anyone walking forward through the design hits the up-to-date marble. When the marble changes, anyone walking back from the code hits the current spec. Customer desire, key result, specification, marble, code — all of it stays continuous as the feature evolves.

I’ve seen what happens when teams skip this. The specs drift. The marbles drift faster. Six months in, no one trusts either. The team is debugging from production and a feature that was supposed to take two weeks balloons into months. Linking the artifacts is cheap. Letting them drift is not.

Decompose features into INVEST stories

With your specifications expanded and live-linked, the team turns to the backlog. Each feature gets broken down into user stories that satisfy INVEST principles:

1. Independent. The story can be worked on without waiting for another story to land first (or, if a dependency exists, it’s known and managed).
2. Negotiable. The story is a placeholder for a conversation, not a contract. The team is free to discuss how to deliver it.
3. Valuable. The story delivers something the customer actually wants. If you can’t draw a line from the story to a key result, reconsider whether it belongs in this sprint.
4. Estimable. The team can size it. If the story is too vague to estimate, it’s too vague to start. Magic estimation is our technique; it’s quick, effective and more accurate than other approaches.
5. Small. It fits comfortably inside a sprint — usually a fraction of one. Big stories hide complexity; small stories surface it.
6. Testable. The BDD scenarios you just elaborated are the tests. This is where elaboration pays the team back: every story arrives with its test plan attached.

Run the decomposition as a working session, focusing on:

• Decomposing epics and features. Product engineers break each feature into INVEST-shaped stories. Smaller is better — within reason — because small stories move through the system faster.
• Validating against customer needs. The product owner and engineers confirm each story reflects what the customer actually wants, referencing personas, key results and event maps. If a story can’t be tied to a key result, that’s a signal — either the story isn’t needed or the key results need work. Fix one or the other before letting the story enter a sprint.
• Documenting consistently. Every story uses the canonical user-story format and ties cleanly to its acceptance criteria, BDD scenarios and engineering model. Inconsistency here is the source of an enormous amount of avoidable friction in sprint refinement.
• Breakdown and estimation. During sprint refinement, the team breaks each story into engineering tasks and sizes them with magic estimation. Surprises that show up here — “oh, we need to add a new endpoint to the customer service” — are exactly what this step is meant to surface.

Surfacing dependencies

As each feature is decomposed, dependencies between stories will surface. A UI story that needs an API. A calculation that depends on a new data feed. A notification that depends on an event the engine doesn’t emit yet.

Capture them as you go. Tag them in your backlog. Sequence them so the dependency is delivered before the dependent story enters a sprint.

Untracked dependencies are how a sprint gets stuck. Tracked dependencies are just sequencing.

Running the workshop

Like the BDD workshops in 3.6 Specification, elaboration runs best as a focused, time-boxed working session. The goal isn’t to grind through every story in one sitting — it’s to establish enough rhythm and shared understanding that the team can finish the work between sessions.

Prepare

• Confirm your three amigos. Same team as in 3.6 Specification — your triad representing product, business and technology. Add UX representation if your scenarios lean heavily on the customer-facing surface.
• Circulate artifacts in advance. Specifications, marble diagrams, tactical event maps and the current sprint backlog — share them well ahead of the session. Walking in cold burns the first hour.
• Set scope. This session is about the current product increment. If you find the team wandering into future increments, that’s a signal to stop and either rescope or replan.
• No guessing. Pull in other team members to answer questions as needed. Assumptions are hidden killers — so don’t assume. Stories don’t move forward with unknown dependencies.

Execute

1. Pick a feature. Start with the highest-value feature in the increment. Confirm the team is aligned on its acceptance criteria and the scenarios formulated in 3.6 Specification.
2. Expand scenarios. Walk each scenario across the testing levels. Write the component-level Gherkin (inclusive of unit and presentation tests). Write the assembly-level Gherkin. If other scenarios are warranted, write those too. Use specific examples — concrete data tables, real-looking values.
3. Link to the engineering model. For each scenario, identify the marble or sequence diagram it implements. Add the link in both directions — in the spec and on the diagram.
4. Decompose into INVEST stories. Break the feature into stories the team can pull, build and finish. Validate each story against the customer’s key results.
5. Surface dependencies. As stories are written, capture dependencies between them and against work outside the sprint.
6. Iterate. Move to the next feature. Repeat until the increment is fully elaborated.

You’re done when the team is confident every story in the increment is INVEST-shaped, every scenario is linked to its engineering model and every dependency is either resolved, sequenced or visibly tracked. If anyone hesitates on any of those, keep working — that hesitation is the gap that will bite you in the sprint.

Outputs

• Elaborated feature specifications. Gherkin scenarios across component-level (inclusive of unit and presentation) and assembly-level (inclusive of end-to-end), expressed in your team’s ubiquitous language.
• Bi-directional links. Every specification linked to its marble or sequence diagram, and every diagram linked back to its specification.
• Sprint backlog. Populated with INVEST-shaped user stories — independent, negotiable, valuable, estimable, small, testable.
• Dependency map. Dependencies between stories captured, tagged and sequenced.

In the next chapter, 3.8 Engineering, we’ll put the finished specifications and stories to work — connecting Gherkin to executable test code, building the feature and confirming each story passes its acceptance tests on the way to the production-ready product increment.

Templates

• Feature specification template — the same template used in 3.6 Specification, extended for elaboration.

Next activity

• 3.8 Engineering