user-stories
/user-stories
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".
- Author
- Sidsaladi9 ↗
- Repository
- persona-os ↗
- Licence
- MIT
- Last repository change
- 30.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 30.08.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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".
Triggers from the description
Original author 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".
How it works
- When to use this
- Before you start (gather these)
- Principles
- Splitting patterns (when a story is too big)
- Process
- Output template
- Worked example (the split that matters)
- Avoid (anti-patterns)
- Tips
SKILL.md preview
---
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.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · Sidsaladi9/persona-os | 100 | MIT |
| daveebbelaar/bama | 100 | MIT |
| daveebbelaar/bawa | 100 | MIT |
| Stijnus/dsh-rev-eng | 100 | MIT |
| MinnThikeTunn/Phan-Tee | 100 | MIT |
| tarunccet/pm-skills | 100 | MIT |
| phuryn/pm-skills | 95 | MIT |
| b33eep/claude-code-setup | 95 | MIT |
| erica-j-01/ai-pm | 95 | MIT |
Database snapshot: 13.11.2026 · package version d753849503eb (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 90create-stories
Writes INVEST user stories with Given/When/Then acceptance criteria and an acceptance-criterion-to-test map for an epic. Use when an epic has no stories yet, when a spec changed and stories must follow, or when the user asks to break work down. - 100user-story-writing
Writes and refines user stories for product backlogs: splits epics into INVEST-compliant stories, drafts Given/When/Then and EARS-format acceptance criteria, and runs definition-of-ready checks. Triggers on: "write user stories", "split this epic", "acceptance criteria for",… - 100create-stories
Breaks one epic into implementable stories with acceptance criteria. Use when the user wants stories for an epic or the next batch of work to build. Not for turning the whole design into epics. - 100create-stories
Breaks one epic into implementable stories with acceptance criteria. Use when the user wants stories for an epic or the next batch of work to build. Not for turning the whole design into epics. - 100create-stories
Breaks one epic into implementable stories with acceptance criteria. Use when the user wants stories for an epic or the next batch of work to build. Not for turning the whole design into epics. - 100create-stories
Breaks one epic into implementable stories with acceptance criteria. Use when the user wants stories for an epic or the next batch of work to build. Not for turning the whole design into epics.