template · story
Story template
Copy-paste skeleton. Five sections, all required. Passes the 9-point DoR before it is pullable.
How to use
The story is the chain's unit of work. Replace every [...] with concrete content. The states section is the section most teams under-use — fill it explicitly. The 9-point DoR at the foot is the gate condition.
text
# Story — [one-line title]
## Story
As [named person, role + context], I want [specific action],
so that [meaningful outcome].
## Journey reference
J[N] — [step name from the journey map]
## States to handle
- Empty: [what the named person sees when there's no data]
- Loading: [what they see while data is on its way]
- Success: [what they see when the activity continues]
- Error: [what they see when something went wrong]
- Edges: [moment-specific edge cases — long names, missing
values, slow networks, repeated actions]
## Acceptance criteria (4–7, at least one negative)
AC1 — Given [person's situation],
When [action],
Then [observable result].
AC2 — Given [...]
When [...]
Then [...]
AC3 (negative) — Given [unhappy path],
When [...],
Then [graceful failure observable].
AC4 — [...]
## Out of scope (this story)
- [Excluded behaviour 1] — Reason: [why deferred]
- [Excluded behaviour 2] — Reason: [why deferred]
## Definition of Ready (the 9-point gate)
1. Story format [✅/⚠/❌] Named person · action · outcome
2. Journey step reference [✅/⚠/❌] J[N] reference
3. ≥3 testable ACs [✅/⚠/❌] Inc. ≥1 negative case
4. Visual / design ref [✅/⚠/❌] Figma frame / Excalidraw
5. Copy / user-facing text [✅/⚠/❌] Empty / loading / error defined
6. Observability signal [✅/⚠/❌] Event name + dashboard panel
7. Dependencies identified [✅/⚠/❌] With owner if external
8. Sized 1–3 days [✅/⚠/❌] Developer-signed
9. Tech feasibility [✅/⚠/❌] TL-confirmed (no spike needed)
## Sign-off (after amigos)
PO: [Name] · [date]
Developer: [Name] · [date]
QA: [Name] · [date]
## Linked artefacts
- Feature Brief: [link]
- Gherkin set: [link]
- Figma: [link]Worked example — the shortcut-submit story
markdown
# Story — Gal submits and advances with ⌘+Enter
## Story
As Gal (head of 8th grade, grading 30 exams on Friday afternoons),
I want to press ⌘+Enter to submit the current exam and advance to
the next one, so that I can grade my batch without lifting my hands
from the keyboard.
## Journey reference
J3 (Teacher reviews and scores per exam) → J4 (Teacher submits one
exam, moves to next) — the friction-bearing transition.
## States to handle
- idle: grader is reviewing the exam; shortcut armed
- submitting: keypress received; button disables, label
becomes "Saving…"; backend call in flight
- success: grade saved; UI snaps to the next exam in queue
- end-of-queue: no more exams; UI shows the dashboard with
"All graded for this class" message
- error/validation: score outside allowed range; shortcut blocked
with inline error
- error/network: backend call fails; toast + retry; grader's
input is preserved
## Acceptance criteria
1. Given Gal is on an exam in the grading view, when she presses
⌘+Enter with a valid score, the exam submits and the next exam
loads within 500ms (p95).
2. Given Gal is on the last exam, when she submits, she sees the
"All graded" message and returns to the dashboard.
3. Given Gal types a score outside the 0–100 range, when she
presses ⌘+Enter, the submit is blocked and the validation
error displays inline. (Negative case.)
4. Given the network drops mid-submit, when the call fails, Gal's
input is preserved and a retry toast appears. (Negative case.)
5. Given Gal uses a non-Mac keyboard, the shortcut is Ctrl+Enter
(platform-aware).
6. Given the page loaded under 200ms, the keyboard shortcut works
from the first interaction without a "hydration" delay.
## Out of scope (this story)
- Multi-exam batch submit — covered in story GR-218
- "Skip without submitting" shortcut — deferred to cycle 6
- Tablet-friendly version — out of this Epic
## Definition of Ready
1. Story format ✅ Named person · action · outcome
2. Journey step reference ✅ J3 → J4
3. ≥3 testable ACs ✅ 6 ACs, including 2 negative cases
4. Visual / design ref ✅ Figma frame "grading/submit-shortcut"
5. Copy / user-facing text ✅ "Saving…", "All graded", error msg
6. Observability signal ✅ `teacher.submitted_grade` event
with `method:shortcut` property
7. Dependencies identified ✅ None external
8. Sized 1–3 days ✅ Esti confirmed 2 days
9. Tech feasibility ✅ TL-confirmed (no spike needed)
## Sign-off (after amigos)
PO: Alex · 2026-05-08
Developer: Maya (dev) · 2026-05-08
QA: Esti (QA) · 2026-05-08
## Linked artefacts
- Feature Brief: /briefs/grading-shortcut.md
- Gherkin set: /tests/grading-shortcut.feature
- Figma: figma.com/.../grading-shortcutWhere this lives in your project
The story lives in the team's tracker (Linear, Jira, GitHub). The 9-point DoR is part of the story itself — not in a separate doc. Trio sign-off comes from amigos.
What to do if a section resists
| Resistance | What it means | Where to go |
|---|---|---|
| Cannot name the person | The Feature Brief is unfinished | Practice · Writing Feature Briefs |
| No J-reference | The brief lacks a journey map, or this story doesn't belong to it | Canon · Journey Mapping |
| States section is "obvious" | Empty/error states are being skipped | Clinic · A story without a state |
| All ACs are happy paths | Amigos hasn't surfaced anti-flows | Practice · Holding amigos |
| Sized "small / medium / large" | The TL hasn't sketched the work | The story is not feasibility-confirmed; back to amigos |
| More than 3 days | This is an epic, not a story | Canon · Slicing & Prioritization |
See also
- Practice — Story writing
- Template — Gherkin scenario set (amigos produces this from the story)
- Checklist — Story · DoR
- Canon — What We Shape · Story Writing