User Story and Acceptance Criteria

User Story and Acceptance Criteria

Overview

This skill takes a feature idea and produces backlog items the team can groom, estimate, and ship. Covers Mike Cohn’s user-story template, the INVEST quality bar (Bill Wake, 2003), Given/When/Then acceptance criteria in Gherkin form, splitting strategies (vertical-slice principle and SPIDR), and the separation between acceptance criteria (per-story, varies) and definition of done (team-wide, stable).

Core Concepts

1. The Mike Cohn user-story template

As a <role>, I want <capability> so that <benefit>.

As a <role> — the user, not the system. “As a user” is the most common failure mode. Name a specific actor type: “As a job seeker”, “As an on-call TAM”, “As a paid subscriber on the Pro tier.”

I want <capability> — the what, written goal-first, agnostic to how.

so that <benefit> — the why. The benefit clause is the most-skipped and most-valuable.

2. INVEST — the quality bar

I — Independent. The story can be built, demoed, and shipped without waiting on another story.

N — Negotiable. The story is a placeholder for a conversation, not a contract.

V — Valuable. The story delivers value to a real user or stakeholder.

E — Estimable. The team has enough context to size it.

S — Small. Fits comfortably inside an iteration. Heuristic: ≤ 50% of one developer’s iteration capacity.

T — Testable. A definite test exists for “done.”

3. Given / When / Then — Gherkin acceptance criteria

Given <some context>
When <some action>
Then <some observable outcome>

And and But chain steps in the same phase.

Rules:

4. The vertical slice rule

A user story must be a thin vertical slice through the architecture — a sliver that touches every layer and delivers end-to-end value.

Horizontal (wrong):

Vertical (right):

5. SPIDR — five ways to split a story

S — Spike. Time-box a research task to remove uncertainty blocking estimation.

P — Path. Split by user path. “Pay with credit card” / “Pay with Apple Pay.”

I — Interface. Split by client or platform. “Filter cases on desktop” / “Filter cases in mobile app.”

D — Data. Split by data scope. “Filter cases for active accounts only” first; “including archived accounts” later.

R — Rules. Relax business rules in the first slice. “Refunds, with no approval workflow” first; “Refunds with manager-approval workflow” later.

6. Acceptance criteria vs Definition of Done

Acceptance Criteria (AC):

Definition of Done (DoD):

A story is done when both its acceptance criteria are met and the team’s definition of done is satisfied.

Templates

Template — user story with acceptance criteria

**Title:** Filter case list by severity

**Story:**
As an on-call TAM,
I want to filter the case list by severity (S1 / S2 / S3 / S4),
so that during a busy on-call shift I can triage S1s first
without scrolling through lower-severity cases.

**Acceptance Criteria:**
1. Given the case list shows ≥ 1 case at each of S1–S4,
   When I select "S1 only" in the severity filter,
   Then only S1 cases are visible
     And the count badge shows the number of visible S1 cases.

2. Given I have applied a severity filter,
   When I reload the page,
   Then the same filter is reapplied
     And the URL contains the filter as a query parameter.

**Out of scope (not in this story):**
- Filtering by status or owner.
- Multi-select severity.

**Estimate:** 5 points

Example — story split using SPIDR

Original (too big, ~21 points):
"As an admin, I want to manage subscription plans."

Split via Path + Rules:
Story A (5 pts) — read-only plan list
Story B (8 pts) — create new plan (USD only; no proration)
Story C (5 pts) — edit plan name (only)
Story D (8 pts) — edit plan price with proration
Story E (3 pts) — deactivate a plan

Definition of Done (team-wide)

# Team Definition of Done

- [ ] Acceptance criteria met (verified by the PM or designate).
- [ ] Unit tests written for new logic; ≥ 80% coverage on changed files.
- [ ] Code reviewed by ≥ 1 other engineer.
- [ ] CHANGELOG.md updated (or marked N/A in the PR).
- [ ] User-facing docs updated (if UI or API surface changed).
- [ ] No new lint warnings; no new TypeScript `any`.
- [ ] Deployed to staging; smoke test passing.
- [ ] Accessibility audit clean for UI changes.

Anti-Patterns

Decision Heuristics

References