Writing User Stories

Overview

Core principle: User stories are a formulaic way of expressing user requirements. Every story identifies the persona of the actor, what they want to do, and the benefit they hope to gain.

When to Use

• You are asked to write a user story
• You are writing GitHub issues for product work or feature requirements
• You are asked to plan a feature and express its requirements as stories

Not for: full product specifications — use the writing-product-specs skill instead.

Story Format

As a [persona]
I want [action or feature]
So that [benefit or value]

Example:

As a non-technical stakeholder
I want to understand what changed in a release without reading code diffs
So that I can communicate updates to customers effectively

Acceptance Criteria

Add clear, testable conditions in Given-When-Then format:

Given I am viewing the project dashboard
When I click the "Filter" button
Then I see a dropdown with all available labels
And the issue list updates to show only matching issues

Stories without acceptance criteria lead to scope creep, unclear completion, and misaligned expectations.

Quality Checklist (INVEST)

Before finalizing a story, verify it is:

• Independent - Can be developed separately from other stories
• Negotiable - Details can be discussed and refined
• Valuable - Delivers clear value to users or business
• Estimable - You can say what done looks like; size it with the estimating-work-items skill
• Small - 8 points or less on the powers-of-two scale; anything bigger is an epic to decompose
• Testable - Success criteria are clear and verifiable

Common Pitfalls

Too technical:

• ❌ "Add a REST endpoint at /api/v2/users with authentication"
• ✅ "As an admin, I want to manage user accounts via API, so that I can automate user provisioning"

Too vague:

• ❌ "Make the dashboard better"
• ✅ "As a manager, I want to see project velocity trends, so that I can forecast delivery dates"

Missing the "why":

• ❌ "As a user, I want dark mode"
• ✅ "As a user, I want dark mode, so that I can reduce eye strain during evening work sessions"

Optional Sections

For stories destined to become GitHub issues, add sections as needed: Dependencies (what must complete first), Open Questions (decisions still needed), Technical Notes (implementation guidance), and Design Assets (mockups, wireframes).