User Stories skill for Claude Code

A story is done well when the team can estimate it in one short conversation, finish it inside half a sprint, and a tester can verify it from the acceptance criteria alone without asking the PM what was meant. A story is a promise of a conversation plus a testable contract, not a mini-spec.

Ground rules

• One story = one thin, vertical slice of user-visible value: UI (or API), logic, and data together. “Build the database table” is a task, not a story.
• The persona is specific (“billing admin on a team plan”), never “the user”.
• The “so that” names an outcome the user cares about, not a restatement of the “I want”.
• Acceptance criteria (AC) describe observable behavior, not implementation.
• Target size: 1–5 days of team effort, or at most ~1/4 of team velocity in points. Anything bigger gets split before it enters a sprint.
• 3–8 AC per story. Fewer than 3 usually means the edge cases were not thought through; more than 8 usually means the story should be split.

Workflow

- [ ] 1. Read the source: PRD, epic, design, support tickets, existing behavior in code
- [ ] 2. Name personas and the job each is trying to get done
- [ ] 3. Map the workflow steps end to end (the backbone)
- [ ] 4. Write stories per step, then split anything over the size limit
- [ ] 5. Write AC: happy path, then rules, errors, permissions, empty/limit states
- [ ] 6. Run INVEST and the definition-of-ready check
- [ ] 7. Order by value and dependency; mark the walking skeleton

Before writing, check the code or product for current behavior. Stories that describe what already exists, or contradict it silently, waste refinement time.

Story format

### <ID>: <short verb-first title>
As a <specific persona>,
I want <capability in the user's words>,
so that <outcome / reason it matters>.

**Acceptance criteria**
1. Given <context>, when <action>, then <observable result>.
2. ...

**Notes:** links to design, PRD requirement ID, open questions
**Out of scope:** what a reader might assume is included but is not

Title rule: verb-first and specific. “Export invoices for a month as CSV” beats “Invoice export”.

Acceptance criteria

Write Given/When/Then for behavior with state; use a plain checklist for static requirements (copy, layout constraints, analytics events).

Coverage checklist for each story:

Category	Ask
Happy path	What does success look like, exactly?
Business rules	Limits, thresholds, rounding, time zones, plan tiers
Validation and errors	Bad input, service failure, timeout — what does the user see?
Permissions	Who can and who cannot? What does “cannot” look like?
Empty and limit states	Zero items, one item, max items, very long text
Concurrency	Two people edit the same thing; double submit
Non-functional	Response time, accessibility, audit log, analytics event

Bad to good:

Bad	Good
“Export works correctly.”	“Given 12,000 invoices dated October, when the admin exports October, then the CSV has 12,000 rows plus a header and totals match the invoice list.”
“Show an error if it fails.”	“Given the export job fails, when the admin opens Exports, then the row shows ‘Failed’, the reason, and a Retry button.”
“Fast.”	“The export link email arrives within 5 minutes for up to 50,000 rows (p95).”
“Only admins.”	“Given a member without the Billing role, when they open Invoices, then the Export button is not shown and GET /exports returns 403.”

INVEST check

Letter	Test	Fix when it fails
Independent	Can it ship without another unfinished story?	Merge tightly coupled stories, or reorder and stub
Negotiable	Does it leave room for the team to choose how?	Remove UI/tech prescriptions not backed by a constraint
Valuable	Would a user or stakeholder notice it shipped?	Fold pure technical tasks into the story they enable
Estimable	Can the team size it in under 5 minutes?	Spike the unknown first (see technical-spike)
Small	1–5 days, ≤ 1/4 velocity?	Split (below)
Testable	Can a tester write a pass/fail check from the AC?	Replace adjectives with numbers and observable results

Splitting

Split vertically. Each resulting story must still pass INVEST on its own. Try these patterns in roughly this order; the first that yields 2–4 meaningful slices wins.

Pattern	Split by	Example
Workflow steps	Steps of the user journey; ship the simplest end-to-end path first	Checkout: guest pay with card → saved cards → promo codes
Business rule variations	One rule per story	Discounts: percentage off → fixed amount → stacking rules
Happy vs. unhappy path	Success first, failure handling next	Upload succeeds → oversized file → virus-scan rejection
Data variations	Types, formats, sources	Import CSV → XLSX → Google Sheets
Interface / platform	Channel or device	Web → mobile web → native app
Operations (CRUD)	Create / read / update / delete	Create a saved view → rename → delete
Simple then complex	Minimal version, then enhancements	Search by exact name → fuzzy match → filters
Defer performance	Make it work, then make it fast at scale	Export ≤ 5k rows synchronously → background export for 50k
Spike + implementation	When the unknown blocks estimation	1-day spike on bank API limits → build sync

Never split by layer (frontend story, backend story, QA story). None of those slices delivers value alone, and they hide integration risk until the end of the sprint.

Worked split

Original epic-sized story (team estimated 13 points, velocity 30):

As a finance admin, I want to export invoices so that I can reconcile in our ERP.

Split by workflow, then data variation, then performance:

ID	Story	AC highlights	Size
INV-1	Export one month of invoices as CSV (≤ 5,000 rows, synchronous)	Column set fixed; row count matches list; UTF-8 with BOM	3
INV-2	Export runs in background with email link for > 5,000 rows	Link valid 7 days; failure shows Retry	5
INV-3	Choose which columns to include; choice remembered	Persisted per user; default = all	2
INV-4	Restrict export to Billing role	Hidden button for others; API 403	1

INV-1 is the walking skeleton: thin, end to end, shippable, and it validates the column format with the ERP before the expensive background work is built. INV-4 could fold into INV-1 if permissions already exist as a reusable check.

Definition of ready

A story enters a sprint only if:

• Persona, need, and outcome are clear and specific
• 3–8 AC including at least one error or permission case
• Sized by the team and under the size limit
• Dependencies identified and either done or scheduled earlier in the sprint
• Designs linked (or “no UI change” stated)
• Open questions answered or explicitly deferred to a follow-up story

Gotchas

• Technical stories in disguise. “As a developer, I want a Redis cache” is a task. Write the user-facing story (“search results load in < 1 s”) and list the cache as an implementation note, unless it is genuine enabling work agreed with the team.
• “So that” restating the want. “I want filters so that I can filter” has no reason. If no outcome can be stated, question whether the story is needed.
• AC that prescribe UI. “A blue button in the top right” locks design. Write “an export action is available from the invoice list” and link the design.
• Hidden ANDs. “Upload and share files” is two stories. Split on every “and” or “or” in the title unless both halves are trivial.
• Splitting until slices lose value. A story that only adds a label is a task in the parent story. Stop splitting at the smallest slice a user would notice.
• AC drift. AC changed mid-sprint without telling QA. Changes to AC after sprint start go through the team, and large changes become a new story.
• Copy-paste personas. If every story says “As a user”, personas were never identified. Go back to step 2.

Verification

• Read each story as the tester: can every AC be marked pass/fail without asking anyone?
• Every story passes all six INVEST letters; note any accepted exception explicitly.
• Sum the sizes: no single story exceeds ~1/4 of velocity or 5 days.
• The first story in the order is a thin end-to-end slice, not a layer.
• No story title contains an unresolved “and”.

Output contract

## Epic: <name> — <one-line outcome>
Personas: <list>    Source: <PRD/link>

| Order | ID | Title | Persona | Size | Depends on |
|---|---|---|---|---|---|

### <ID>: <title>
As a ..., I want ..., so that ...
**Acceptance criteria**
1. Given ..., when ..., then ...
**Notes / Out of scope / Open questions**

## Split rationale
<pattern used and why; what the walking skeleton proves>