User Stories skill for Codex

A good story is a thin vertical slice of user-visible value that one team can finish, test and demo inside a sprint. Every story names a real role, says why the role wants it, and is small enough that the team agrees on its size within two minutes of discussion.

Format

As a <specific role>,
I want <capability expressed as behaviour>,
so that <outcome the role cares about>.

• Role: a real segment (“workspace admin”, “first-time buyer”), never “the user” or “the system”. If the beneficiary is a developer or operator, say so; technical work that no person benefits from directly is a task, not a story.
• Capability: behaviour, not a UI widget. “Filter invoices by status” not “add dropdown”.
• Reason: the outcome, not a restatement. “so that I can filter invoices” is circular.

INVEST check

Letter	Test question	Fix when it fails
Independent	Can it ship without another story in this batch?	Merge dependent pair, or reorder and note the dependency
Negotiable	Does it leave room for the team to choose how?	Remove implementation detail from the story text
Valuable	Would a user or the business notice it shipped?	Combine with the slice that makes it visible
Estimable	Can the team size it now?	Add a time-boxed spike story first
Small	Fits in half a sprint or less?	Split (patterns below)
Testable	Can you write Given/When/Then for it?	Clarify the outcome, then use $acceptance-criteria

Splitting patterns

Always split vertically: each piece touches every layer it needs (UI, API, data) and is demoable. Never split into “frontend story” and “backend story”.

Try these in order and stop at the first that yields 2-5 sensible pieces:

Pattern	Use when	Example for “export reports”
Workflow steps	Story describes a multi-step process	Choose report; configure columns; download
Happy path first	Error and edge handling dominates effort	Export succeeds; then handle >100k rows; then retry on failure
Business rule variations	Several rules or policies apply	Export own reports; then team reports with permission check
Data variations	Several input types or formats	CSV first; XLSX later; PDF later
Interface variations	Several entry points or devices	Web export; then scheduled email export; then API
Operations (CRUD)	“Manage X” stories	Create; view; edit; delete
Defer performance	Speed is a separate concern	Works for 1k rows; then streams for 1M rows
Spike	The team cannot estimate due to unknowns	1-day spike: can the PDF lib render our charts?

After splitting, check each piece still has a “so that”. If one piece has no value on its own (e.g. “set up export table”), fold it into the first slice that uses it.

Workflow

- [ ] 1. Read the source (PRD, epic, issue) and AGENTS.md for ticket conventions
- [ ] 2. List roles and the outcomes each needs; ask if a role is unclear
- [ ] 3. Draft one story per outcome; ignore size for now
- [ ] 4. Run INVEST on each; split anything not Small or not Estimable
- [ ] 5. Add 2-6 acceptance criteria per story (or link to them)
- [ ] 6. Order the backlog: walking skeleton first, then by value and risk
- [ ] 7. Present the backlog; file to the tracker only after the user approves

Walking skeleton first

The first story should be the thinnest end-to-end path through the whole feature, even if ugly: it proves the architecture, gives a demo, and de-risks integration. For a “team invites” epic: “As an admin, I want to invite one person by email so that they can join my workspace”, with no roles, no bulk, no resend.

Story card template

### <ID> <short imperative title>
As a <role>, I want <capability>, so that <outcome>.

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

**Notes:** <constraints, links to designs, PRD requirement IDs (R3, R7)>
**Out of scope:** <what the next slice will add>
**Dependencies:** <story IDs or none>
**Estimate:** <points or T-shirt, filled in by the team, not by you>

Never fill in estimates yourself. Effort belongs to the team that will do the work; you may flag stories that look large relative to their siblings.

Filing stories to a tracker

Filing creates shared, visible tickets, so show the full list and get a clear yes first. With the GitHub CLI (needs network and gh auth):

gh issue create --title "Invite one member by email" \
  --body-file /tmp/story-01.md --label "story" --label "epic:invites"

For Jira, Linear or other trackers, produce a CSV or markdown file the user can import, unless an MCP connector or CLI for that tracker is configured in this Codex session.

Reviewing an existing backlog

For each story, report: INVEST failures, missing role or reason, horizontal splits, stories over half a sprint, and duplicates. Then propose the rewritten story, not just the critique.

Red flags to call out:

• “As a developer, I want a database table…” - task, not story; fold into a slice.
• “As a user, I want the system to be fast” - non-functional requirement; becomes an acceptance criterion or a constraint with a threshold.
• Stories that say “and” in the capability usually hide two stories.
• Ten stories with identical “so that” text usually means one story split horizontally.
• A story nobody can demo at sprint review is not done-able.

Gotchas

• Stories are a placeholder for a conversation, not a contract. Keep detail in acceptance criteria and notes, and keep the story sentence short.
• Do not write stories for refactors or upgrades that users never see; track them as technical tasks with a stated reason (see $technical-debt-triage).
• Splitting by sprint (“part 1”, “part 2”) is not splitting; each part must deliver something usable on its own.
• Bugs are not stories; file them with reproduction steps.

Verification

For each story: read only the card and try to write two acceptance tests and one demo script line (“open X, do Y, see Z”). If either is impossible, the story is not ready. Count the backlog: if the first three stories together do not produce a demoable end-to-end flow, reorder around a walking skeleton.