writing-user-stories

Write user stories in the format "As a [persona], I want [action], so that [benefit]" to capture who needs it, what they want, and why. Then add Given-When-Then acceptance criteria so the story has clear, testable completion conditions.

INVEST verifies a story is Independent, Negotiable, Valuable, Estimable, Small, and Testable. Checking each criterion before finalizing prevents stories that are too large, vague, or impossible to verify.

Acceptance criteria in Given-When-Then format state a precondition (Given), a user action (When), and the expected outcome (Then). For example: "Given I am viewing the dashboard, When I click Filter, Then I see a dropdown with all available labels."

Use user stories when breaking a feature into requirements or drafting product issues. For full product specifications covering an entire product or major initiative, use a dedicated product specification skill instead.

The benefit clause explains why the feature matters, preventing stories like "As a user, I want dark mode" with no rationale. Stating the benefit, such as reducing eye strain during evening work, keeps implementation aligned with real user value.