part four · story writing
Story Writing
Person, moment, done, out-of-scope. Plus the nine-point Definition of Ready.
A story is a unit of work scoped to a single moment in a single person's activity, deliverable in 1–3 days, with at least three testable acceptance criteria. The corpus is opinionated about the form. The form is what makes the story interpretable across the trio without further conversation.
The story format
As [named person, with brief context], I want [specific action], so that [meaningful outcome].
Always with a named person. Never as a user.
As Gal, an exam grader at our customer's flagship campus, I
want the LMS to display Hebrew names correctly without
re-typing, so that I can grade without breaking my flow.The role description after the name is what carries the context the developer needs. Gal at the customer's flagship campus is different from Gal who tests the LMS internally. The story is for the first.
What a story carries
Every story has the same five sections. Less and the trio is filling in gaps in their head; more and the story has become a feature.
| Section | What it contains |
|---|---|
| Story sentence | As–I want–so that |
| Journey reference | J-number from the journey map |
| States to handle | Empty, loading, success, error, key edge cases |
| Acceptance criteria | 4–7 testable Given/When/Thens, including at least one negative |
| Out of scope | What this story does not do, even though it is tempting |
The states section
This is the section most teams underuse. Every interactive moment has at least four states:
- Empty — there is no data yet.
- Loading — the data is on its way.
- Success — the data has arrived and the activity continues.
- Error — the data didn't arrive or arrived broken.
Plus the edge cases the moment surfaces — long names, missing values, slow networks, repeated actions.
The corpus pattern: a story missing the states section produces a feature that breaks on second use. The states are surfaced before code begins, in story-writing — not after, in QA.
The Definition of Ready
A story is ready — pullable into a sprint — only when nine points are confirmed.
1. Story format ✅ Named person, action, outcome
2. Journey step reference ✅ J6 — Hebrew name editing workaround
3. ≥3 testable ACs ✅ 4 ACs, including 1 negative case
4. Visual / design ref ✅ Figma frame V2-J6-Names-State-A
5. Copy / user-facing text ✅ Empty, loading, error all defined
6. Observability signal ✅ Event name "name.display.normalized"
7. Dependencies identified ✅ None outside this Epic
8. Sized 1–3 days ✅ Sized 2 days by Tech Lead
9. Tech feasibility ✅ Confirmed in Epic kickoff (no spike needed)A story missing one or more points is not ready. It can be pulled into amigos, where the missing points are surfaced and assigned. It cannot be pulled into a sprint until all nine are green.
Sizing
Three sizes. Larger is not allowed.
| Size | Duration | Pattern |
|---|---|---|
| Small | <1 day | Single moment, single state, no surprises |
| Medium | 1–2 days | Standard moment with states, Gherkin scenarios already known |
| Large | 2–3 days | Moment with multiple states or new infrastructure |
Anything larger is split. The split is part of story-writing; it is not deferred to we'll see how it goes. A story that arrives at amigos at 5 days is a story that has not been written; it is a wish.
What the story is for
The story is for three audiences, all of whom must read it and arrive at the same understanding without further conversation:
- The developer — knows what to build.
- The QA — knows what to test.
- The PO — knows what they will accept.
Amigos (Part 5) is the session that confirms the convergence. If amigos surfaces disagreement, the story goes back for rewriting before code begins.