Purpose
A user story states a requirement through the user's eyes as value, not a tech spec. The goal is to start a conversation about value and agree on acceptance criteria. A good story passes INVEST and has criteria in Given/When/Then.
Template
# Story: <name>
> As a <role>, I want <action>, so that <value>.
## Acceptance Criteria (Given/When/Then) — a happy scenario and an edge/error scenario.
## Notes — dependencies, mockup, non-goals. ## Estimate: <points>
Example 1 — happy + edge
# Story: Auto-clip videos into Shorts
> As a content creator, I want auto-clipping of a long video into Shorts, so that I publish more often without manual editing.
Scenario: Clipped successfully
Given a 10+ min video is uploaded When I click "Clip" Then I get ≥3 vertical 9:16 clips, each ≤60s with subtitles
Scenario: Too short
Given a 30s video When I click "Clip" Then "needs a video of 1+ min" is shown and the button stays disabled
Example 2 — another domain
# Story: Save a card to favorites
> As a knowledge-base user, I want to add cards to favorites, so that I quickly return to needed tools.
Scenario: Add to favorites
Given I opened a tool card When I click the star Then it appears in "Favorites" and the star fills
Scenario: Survives reload
Given a favorited card When I reload Then it stays in "Favorites"
INVEST
Independent · Negotiable · Valuable · Estimable · Small · Testable.
Quality checklist
- "As… I want… so that…" with real value.
- Role is a concrete user, not "the system".
- Criteria in Given/When/Then, observable result.
- At least one edge/error covered.
- Passes INVEST (esp. Small & Testable).
Common mistakes
"Value" repeats the action; giant story; no acceptance criteria; a tech task disguised as a story; happy path only.