Story Elaboration
Story elaboration adds to a story selected for an iteration the detail, the examples and the acceptance criteria a team needs to build it and to demonstrate it. It is held as a workshop, as close as possible to the iteration that will deliver the story, with those who will execute it: the business experts, the customer representative, the person who will test it and the business analyst who facilitates the session. The Agile Extension to the BABOK Guide places it in the Delivery horizon and puts it under two constraints: just in time, just enough. Its output is a shared understanding of what "Done" means for this story.
Goal
Story elaboration defines the detailed design and the acceptance criteria of a story, as needed to deliver a working solution. It works on one story at a time. The Agile Extension to the BABOK Guide makes it the lowest level of decomposition.
Story decomposition settles how many stories there are and where each one sits in the hierarchy. Elaboration takes a story already cut to the right size and fills it in. What gets elaborated is most often a user story, sometimes a use case or a detailed requirement carried on the backlog.
§7.19.2 places the technique in the Delivery horizon. Table 7.0.1 files it under requirements management and on the internal-team side.
Usage
When to use it
- A story selected for the upcoming iteration: elaborate it in the days before the planning workshop.
- Acceptance criteria missing or impossible to verify: the session rewrites them in a form the tester can run.
- The customer's intent is ambiguous: examples with figures in them settle what an abstract wording leaves open.
- A business rule to confirm: the expert who holds it answers in the room.
- Detail written months ago: hold the session again rather than trust a text the release has overtaken.
When not to use it
- A story too large for one iteration: hand it back to story decomposition before adding any detail.
- A story that will not ship for several iterations: backlog refinement is enough until then.
- A technical unknown that blocks every answer: a spike removes it before the session has anything to work on.
Description
Who is in the room
The Agile Extension names four roles: the business experts who hold the rule, the customer representative who needs the story, the person who will test it and the business analyst who facilitates the session and challenges the story. The first three bring the three angles under which a story turns out to be incomplete: the rule, the intent, the verifiability. Three Amigos, a term from George Dinwiddie carried by the Agile Alliance, names the examination of a work item under the business, development and testing perspectives. The guide puts no developer on its list: §7.19 covers two of those perspectives, business and testing, and the business analyst takes the developer's seat. In practice, a session nobody will leave in order to build writes criteria without anyone in the room costing them.
The business analyst holds two roles there. Facilitating means keeping the subject on one story and stopping the session when the answer is missing. Challenging means asking, for each criterion, how it will be verified and on what data. The Agile Extension is firm on this: the practitioner continually develops and communicates moving requirements, which demands as much facilitation as communication.
Just in time, just enough
Elaboration covers only the stories selected for the upcoming iteration. It is held in preparation for the planning workshop, early enough for the team to estimate on written detail. The practical marker is one iteration ahead.
The guide states two timing faults. Too early: the information ages, the release changes around it and the detail has to be elicited again before it is of any use. Too late: the team waits its turn or starts on a story whose criteria are unwritten, and the question then gets settled in the code.
The guide puts three strengths to the credit of the technique: less elicitation time and less documentation, no detail produced for a feature that will have changed before implementation, a team that stays on the highest-priority feature of the backlog.
The acceptance criteria
Elaboration clarifies, adds or removes acceptance criteria. The format and the construction of those measures belong to acceptance and evaluation criteria. Clarifying: a criterion written as an intention receives a value, a threshold or a date. Adding: a question from the business expert uncovers a case nobody had covered. Removing: a criterion describes another story or prescribes a technical solution the team is still free to choose.
Every criterion has to be settled by a test the tester can write before construction starts. The given, when, then form, made common by behaviour driven development, forces the starting state, the action and the observable result to be named. Ron Jeffries gave the reason for it in 2001 when he placed confirmation beside the card and the conversation: what is agreed out loud is lost, except in the form of a test somebody can run.
The items the session can produce
The guide lists five possible outputs. Each one answers a question left open.
| Item | What it settles | When to produce it |
|---|---|---|
| Task definitions and breakdowns | How the team shares out the building of the story. | The story fits in the iteration but nobody sees where to start. |
| Examples and scenarios | The customer's intent, case by case, on concrete values. | Two people in the room read the same criterion differently. |
| Low-fidelity models (data model, data flow diagram) | The structure of the data or its path between systems. | The story creates a new entity or crosses several applications. |
| Screen or report mock-up | The fields displayed, their order, the labels, the path to confirmation. | The story plays out in an interface the customer will see. |
| Input and output table | The data contract between two components or two teams. | Another team supplies the data or consumes it. |
The guide gives them as optional. Producing all five on every story is the sign that the workshop has taken back the detailed up-front specification the agile approach sets aside.
What the workshop leaves behind
The result is a shared understanding, among the stakeholders, of what has to be delivered for the story to reach the "Done" state. The criteria, the scenarios, the mock-up and the data table are the written traces of that conversation. They attach to the story in the backlog tool, where whoever builds and whoever tests find them again. A separate write-up is out of date at the first change of criterion.
What makes an elaboration fail
The story that should have gone back to splitting
The session discovers that a story does not fit in one iteration. The guide provides for this case: elaboration identifies opportunities to decompose. The right move is to hand the story back to decomposition and to elaborate the pieces when they are selected in their turn. The common fault is to carry on, then produce two hours of detail on a story that is split the following week.
The level of detail misjudged
The guide acknowledges the difficulty without resolving it: finding the level at which the requirements can be developed, tested and compared to the criteria. Too little detail: the team invents the rule while building. Too much detail: the team follows a design settled by people who will not build it. The session stops when the tester can write the test and when whoever builds needs no second conversation to start.
The session without a tester
The tester is the only one whose trade is to ask how anyone will know. Without one, the criteria get written as plausible intentions and the question of verification comes up at the end of the iteration, when the answer costs rework. This is the person most often sacrificed to the schedule, because they seem to come later.
AI considerations
A language model works well on shaping the outputs of the session. From a story and its criteria, it proposes given, when, then scenarios and lists the cases a room under time pressure forgets: the boundary value, the empty list, the double submission, the cancellation halfway through. It also turns a set of criteria into the skeleton of an input and output table, which the session corrects instead of building.
Elaboration is governed by just enough, and a model produces thirty scenarios at the same cost as six. A generated list poured onto the story as it stands breaks the just enough: the team will spend its iteration satisfying cases nobody asked for. The prompt that helps sets a ceiling and makes each scenario justify itself against a criterion.
The business rule escapes the model. That a subsidised handset bars any move below a subscription tier before the contract matures is a contractual fact held by the billing expert. A model asked about it will produce a plausible rule, indistinguishable in form from a true one. Mock-ups and data tables carry field names and sample records often taken from real data; the Federal Act on Data Protection (FADP) applies to that extract as it does to the rest.
Examples
A Swiss telecom operator elaborates the story selected for the next iteration: "As a customer, I want to move to a cheaper subscription from the next billing cycle, so that I stop paying for data I do not use." It arrives from decomposition with three acceptance criteria. The session comes out with four scenarios, a mock-up and a data table.
| Scenario | Given | When | Then |
|---|---|---|---|
| Takes effect at the next cycle | A customer on CHF 39 a month whose billing cycle ends on 30 April | The customer confirms the move to CHF 29 a month on 20 April | The CHF 29 subscription applies from 1 May |
| Confirmation before commitment | A customer on CHF 39 a month who has chosen the CHF 29 subscription | The confirmation screen is displayed | It carries both prices, the monthly saving of CHF 10 and the date it takes effect |
| Second change blocked | A change already scheduled for 1 May | The customer asks for a second change before that date | The service refuses it and displays the date the change in progress takes effect |
| No proration of the current cycle (added in the session) | A billing cycle of 30 days, 1 to 30 April | The April invoice is issued after a confirmation on 20 April | It carries CHF 39, with no refund for the 10 remaining days |
The fourth scenario is the one decomposition had not seen. The billing expert asks what becomes of the current cycle, and the session settles the rule: nothing is given back. On a cycle of 30 days, a confirmation on 20 April leaves 10 days at the old price. Proration would have credited the monthly difference of CHF 10 pro rata over those 10 days, that is CHF 10 × 10 ÷ 30 = CHF 3.33 rounded to the centime. That amount is not credited: the April invoice stays at CHF 39.00 and the CHF 29.00 price runs from 1 May. The figure serves here to measure what the rule sets aside.
The low-fidelity mock-up of the confirmation screen fits into four lines and a button: current subscription CHF 39.00, new subscription CHF 29.00, monthly saving CHF 10.00, takes effect on 1 May. The input and output table fixes the contract of the service.
| Direction | Field | Sample value | Origin or rule |
|---|---|---|---|
| Input | Identifier of the current subscription | MOB-39 | Customer contract |
| Input | Identifier of the target subscription | MOB-29 | Catalogue of eligible subscriptions |
| Input | Date of the request | 20.04 | Timestamp of the service |
| Input | Last day of the current cycle | 30.04 | Billing calendar |
| Output | Date it takes effect | 01.05 | First day of the next cycle |
| Output | Monthly saving | CHF 10.00 | CHF 39.00 − CHF 29.00 |
| Output | Amount invoiced for the current cycle | CHF 39.00 | Current price, proration set aside |
| Output | Confirmation message | "Your subscription moves to CHF 29.00 a month on 1 May." | Template carrying the date it takes effect |
Visualisations
The technique draws as two panels. On the left, the story as it comes out of decomposition: a card carrying its single sentence. On the right, the same story after the session, surrounded by the items the workshop has attached to it, the acceptance criteria, the scenarios, the mock-up and the input and output table. A dashed arrow leaves the second panel, labelled with the one case that is not settled in the room: the story too large, handed back to splitting.
The drawing carries the invariant of the technique: the story keeps its identity from one panel to the other, only its detail grows. A right-hand panel carrying several cards instead of one would be drawing decomposition.
Cost
| Phase | Level | Justification |
|---|---|---|
| Preparation | Low | The story and its first criteria exist; the facilitator re-reads the backlog branch and convenes four people. |
| Execution | Medium | One to two hours per story, to be repeated for every story selected in every iteration. |
| Documentation | Low | Criteria, scenarios and mock-ups attach to the story in the backlog tool; no separate document to maintain. |
Tooling
The backlog management tool receives the outputs of the session: an acceptance criteria field on the story, sub-tasks for the breakdown, attachments for the mock-up. Criteria filed in a comment or in a linked document escape the team views and the Definition of Done.
The shared board, Miro, Mural or a wall and sticky notes, carries the session: the examples move around, group and get thrown away. This surface suits the sketch of a data model or of a flow, which the session draws to settle a question and then abandons.
The low-fidelity mock-up tool, Balsamiq or Figma in wireframe mode, plays the role the guide provides for. A mock-up that is too finished moves the conversation to colours and spacing, when the session is after the fields and the rules.
The executable scenario tool, Cucumber, SpecFlow or an equivalent, extends the session when the team practises behaviour driven development: the scenarios written in the workshop become tests that run. A team that does not run them keeps the same writing template without the tooling.
Sources
- IIBA, Agile Extension to the BABOK Guide, §7.19 Story Elaboration: the object of the technique, its place in the Delivery horizon, the workshop setting and the list of roles, the discipline of just in time and just enough, the preparation for the planning workshop, the elements: elicitation, the referral back to decomposition, the acceptance criteria and the five optional outputs, together with the strengths and limitations stated, among them the two timing faults and the difficulty of judging the level of detail.
- IIBA, Agile Extension to the BABOK Guide, §7.0, table 7.0.1 Selecting the Right Technique: the technique filed among the requirements management techniques, on the internal-team side.
- Ron Jeffries, Essential XP: Card, Conversation, Confirmation, XProgramming, 2001: confirmation as the third component of a story, earlier than the technique it illuminates without defining it.
- Agile Alliance, What are the Three Amigos?: the three business, development and testing perspectives brought together on a work item, attributed to George Dinwiddie.