User Stories

---
name: user-stories
description: Breaks an epic, spec, or feature into well-formed user stories with Given/When/Then acceptance criteria, applies INVEST, and splits stories that are too big. Use when a PM says "break this epic into stories", "write user stories", needs "acceptance criteria for X", wants to "split this story", or asks to "turn this PRD into a backlog".
tier: quick
time: 20-30 min
inputs: the epic or spec to break down
outputs: projects/<project>/user-stories.md
---

# User Stories

Turn a fuzzy epic, spec, or feature into a backlog of small, testable, independently shippable user stories. Each story names a user, a capability, and an outcome, carries acceptance criteria a developer and tester can verify, and is sliced as a thin vertical end-to-end path — never a horizontal technical layer. Where a story is too big, split it with a proven pattern rather than guessing.

**Grounded in:** *User Story Mapping* — Jeff Patton: vertical slices and story mapping, with INVEST and Given/When/Then.
**Go deeper (The Product Channel):** [Guide to Product Requirements Documents](https://sidsaladi.substack.com/p/guide-to-product-requirements-documents)

## When to use this
- An epic or spec is too large to estimate or build, and needs decomposing.
- You're handed a PRD and need a ready-to-groom backlog out of it.
- A single story keeps growing or hides several decisions and should be split.
- A story exists but its acceptance criteria are vague, missing, or untestable.
- Sprint planning needs stories small enough to fit a sprint with clear "done."

## Before you start (gather these)
- The epic / spec / feature you're decomposing — the scope boundary.
- The user or persona who benefits (and any distinct user types involved).
- The outcome / goal: what changes for them when this ships.
- If pointed at a PRD or doc, read it first and pull the above from it.
- If scope, persona, or outcome is unclear, ask before slicing — don't invent them.

## Principles
- **Story form:** As a [user/persona], I want [capability], so that [outcome]. The "so that" is non-negotiable — it's the user value and the reason to build.
- **INVEST** every story:
  - *Independent* — minimal ordering dependencies on other stories.
  - *Negotiable* — a conversation, not a frozen contract of implementation detail.
  - *Valuable* — delivers observable value to a user or the business.
  - *Estimable* — the team understands it well enough to size it.
  - *Small* — fits comfortably in a sprint; ideally a few days.
  - *Testable* — you can write the acceptance criteria that prove it's done.
- **Acceptance criteria as Given/When/Then** — Given [context], When [action], Then [observable result]. Cover the happy path AND edge cases (empty, invalid, unauthorized, limits, failures).
- **Vertical slices over horizontal** — each story is a thin end-to-end path that delivers value (UI + logic + data for one capability), not a layer ("build the API," "build the schema") that delivers nothing alone. *Exception for quality-bar / model-accuracy work:* a story that proves a probabilistic capability hits its bar against an eval set (detection/scoring verified offline, no UI yet) is a legitimate first vertical slice — the verifiable accuracy *is* the value.
- **Acceptance criteria for probabilistic / ML / quality-bar features** — Given/When/Then is deterministic, but ML behavior is only correct ~85% of the time, so don't write AC as if each case must pass. Instead make the criteria threshold-based and measured against a fixed eval set / golden dataset: define a labeled dataset, set precision/recall (or F1, accuracy) targets, and write AC like "Given the golden eval set of N labeled examples, when the model runs, then precision ≥ 0.90 and recall ≥ 0.80." Specify the dataset, the metric, and the threshold so the AC is still pass/fail — just measured statistically rather than per-instance.

## Splitting patterns (when a story is too big)
- **Workflow steps** — slice along the steps of a process. "Checkout" → enter address → choose shipping → pay → confirm.
- **Business-rule variations** — one story per rule. Discount: percentage off, then BOGO, then loyalty tier.
- **Happy vs. edge path** — ship the happy path first, edges as follow-ups. "Pay with valid card" before "handle declined card."
- **Simple vs. complex** — do the basic case, defer the hard one. "Search by exact name" before "fuzzy + filters search."
- **Data / interface variations** — split by input type, format, or channel. "Upload CSV" before "upload Excel and JSON."
- **CRUD operations** — split create / read / update / delete. "View saved reports" can ship before "edit" and "delete."
- **Defer performance** — make it work, then make it fast. "Generate report (any speed)" before "generate report in <2s."

## Process
1. **Identify the user(s) and the epic's outcome** — who benefits and what changes for them. List distinct personas if more than one.
2. **Slice into vertical stories** — break the outcome into thin end-to-end capabilities, each delivering value on its own. Reach for a splitting pattern when a slice is still chunky.
3. **Write each in story form** — As a / I want / so that. Confirm the "so that" states real value.
4. **Add Given/When/Then acceptance criteria** — at least one happy-path scenario plus the edge cases that matter (invalid, empty, unauthorized, limits, failure).
5. **Check INVEST and bound the slice** — run each story through the six letters; flag and fix anything that fails. State what's explicitly out of scope for the story (deferred work, things handled elsewhere) so the boundary is unambiguous.
6. **Split anything too big** — if a story fails *Small* or *Estimable*, or hides multiple decisions, apply a splitting pattern and re-check.
7. **Sequence** — order by dependency and value; surface the thinnest slice that proves the epic end-to-end first.

## Output template
Copy-paste per story:

```
### [Story title]

As a [user/persona],
I want [capability],
so that [outcome].

**Acceptance criteria**
- Given [context], when [action], then [observable result].
- Given [edge context], when [action], then [result].
- Given [error/limit context], when [action], then [result].

**Notes / edge cases**
- [assumptions, open questions, data or rule details]

**Out of scope**
- [explicitly not in this story — deferred or handled elsewhere]
```

**Suggested build order**
1. [story] — thinnest end-to-end slice; proves the path.
2. [story] — [why next: unblocks X / highest value]
3. [story] — ...


## Worked example (the split that matters)
An epic arrives as *"bulk CSV export."* The lazy split is by layer — backend story, frontend story, QA story — which produces three stories none of which ship value alone.

The useful split is by **thin vertical slice**, each independently shippable:

1. *As an ops manager, I want to export the current filtered view as CSV, so I can hand my director numbers without asking data for a pull.* — one view, ≤1,000 rows, synchronous download.
2. *As an ops manager, I want exports over 1,000 rows to arrive by email, so a big export doesn't time out in my browser.*
3. *As an ops manager, I want my last export's filters remembered, so the Monday report takes one click.*

Story 1 alone is worth shipping. That's the test: if a story can't be released on its own and be worth something, it's a task, not a story.

Notice the "so that" clauses — each names a real outcome, not a restatement of the action. *"so that I can export a CSV"* is the tell that the value wasn't understood.

## Avoid (anti-patterns)
- **Horizontal / technical-layer stories** — "build the API," "create the schema," "wire up the service." They deliver no user value alone. Slice vertically. *Exception:* a detection/eval-only story for an ML or quality-bar feature — verified against an eval set with no UI — is not a horizontal layer; the measured accuracy is real, demonstrable value and is a valid first slice.
- **Untestable acceptance criteria** — "works well," "is fast," "is intuitive." If you can't write a pass/fail check, rewrite it as Given/When/Then.
- **Giant stories** — one story hiding a dozen decisions, rules, or screens. If you can't estimate it, split it.
- **Missing the "so that"** — a capability with no stated user value. If there's no outcome, question whether to build it.

## Tips
- One verb per story. "Create and edit and export" is three stories.
- If estimation triggers an argument, the story is too big or too vague — split or clarify.
- Write the edge-case criteria first sometimes; they expose hidden scope fast.
- A story you can demo in one sentence ("watch me pay with a saved card") is the right size.
- Keep acceptance criteria about observable behavior, not implementation.
- Name the persona specifically ("returning shopper," not "user") — it sharpens the slice.