A2 · chapter overview
Decomposition: from vision to user stories
A vision is a destination, not a plan. This chapter turns it into a dependency-ordered ladder of small, valuable, testable user stories — each one a thin slice the loop can build and prove before the next begins. Decomposition is the human work the agent cannot do for you, and it is what makes every later rung tractable.
By the end of A2 you can take a one-line product vision and write it as a backlog: value not tasks, the Connextra story form and the three Cs, the INVEST test for a good story, Given/When/Then acceptance criteria, how to split a story that is too big, and how to order the result into a value ladder — all practised on the Portal.
The shape of decomposition
Decomposition is the move from a vision to a backlog: a list of stories small enough to build in one pass, valuable enough to demo, and ordered so each rung stands on the ones below it. A story is not a task. A task names work to do; a story names a change in what someone can do once the work lands. Stated that way, every story is independently demonstrable, and the order between them is a ladder of value rather than a checklist of chores.
The interactive below splits one Portal vision into that ladder. Step up the rungs and the readout reports what the slice delivers, what it depends on, and the acceptance check that proves it — the same three questions every story in this chapter must answer.
A Portal vision, split into a value ladder
A good decomposition is a ladder, not a pile: every rung delivers value on its own and rests on the rungs below it, so the loop can build and prove one at a time.
Module navigation
Seven modules carry the chapter from the idea of value to a worked decomposition of the Portal backlog. They build in order: name what a story is, write it in a shared form, test it against INVEST, pin it down with acceptance criteria, split it when it is too big, order the result into a value ladder, and then run the whole sequence on the Portal.
Value, not tasks
Why a story names a change in what someone can do, not the work to do — and why that makes it demonstrable.
The Connextra form and the three Cs
Writing a story as role, want, and reason — and treating it as a card, a conversation, and a confirmation.
INVEST: what a good story looks like
The six tests — independent, negotiable, valuable, estimable, small, testable — a story should pass.
Acceptance criteria with Given/When/Then
Pinning a story down with concrete examples of the behaviour that proves it is done.
Splitting stories that are too big
Patterns for cutting a story too large for one rung into thinner slices that each still deliver value.
The value ladder
Ordering the backlog so each story rests on the ones below it and value accrues rung by rung.
Workshop — decomposing Portal
Running the full sequence on the Portal vision: from one line to an ordered, tested backlog.
This chapter turns the A1 framework into a backlog: the loop needs a stream of thin, provable slices to run on, and decomposition is where they come from. The previous chapter, A1 — Why an Agile Agent Workflow, makes the case for the workflow and names its parts; A2 supplies the work it operates on.
References
The sources this chapter draws on for the story form, the quality tests, and example-driven acceptance, and where the framework it feeds is defined in the course.
Sources
- Cohn, M. — User Stories Applied — stories as value, the three Cs, and splitting.
- Wake, B. — INVEST in Good Stories — the six tests a well-formed story should pass.
- Cucumber — Gherkin reference — the Given/When/Then form for acceptance criteria.
- Adzic, G. — Specification by Example — concrete examples as the shared definition of done.
Related in this course
- A1 · Why an Agile Agent Workflow — the framework this chapter turns into a backlog.
- A1.04 · Two layers: roadmap and specs — the spec layer each story feeds.
- Course home · all chapters
- Companion · Functional Programming in Elixir — the Portal’s Elixir and OTP foundations.