user-stories
Guidelines for writing effective user stories with clear acceptance criteria. Use when creating issues from discovery findings.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for crafting high-quality user stories and clear acceptance criteria. By implementing the INVEST criteria and structured templates, it helps teams transform discovery findings into actionable, well-defined development tasks that improve project clarity, reduce scope creep, and streamline the software development lifecycle.
Use Cases
- Converting discovery meeting notes and research findings into structured, developer-ready GitHub or Jira issues.
- Refining vague feature requests into small, independent user stories that follow the INVEST (Independent, Negotiable, Valuable, Estimable, Small, Testable) framework.
- Defining measurable and specific acceptance criteria to guide QA testing and ensure that the 'Definition of Done' is met for every feature.
- Decomposing large, complex features into manageable pull requests (PRs) using strategies like user flow steps or data entity splitting to maintain high development velocity.
| name | user-stories |
|---|---|
| description | Guidelines for writing effective user stories with clear acceptance criteria. Use when creating issues from discovery findings. |
User Stories Skill
This skill provides guidance for writing well-formed user stories with clear acceptance criteria.
User Story Format
As a [type of user],
I want [goal/desire],
So that [benefit/value].
Examples
Good:
As a registered user,
I want to reset my password via email,
So that I can regain access to my account if I forget my password.
Bad:
Add password reset feature.
The good example captures WHO needs it, WHAT they need, and WHY.
INVEST Criteria
Good user stories are:
| Criteria | Description |
|---|---|
| Independent | Can be developed separately from other stories |
| Negotiable | Details can be discussed and refined |
| Valuable | Delivers clear value to the user |
| Estimable | Can be sized (fits in a single PR) |
| Small | Implementable in one PR, not weeks of work |
| Testable | Has clear acceptance criteria to verify |
Checking Your Stories
- Independent: Does this require other stories to be done first? If so, document the dependency.
- Negotiable: Is there flexibility in HOW this is implemented?
- Valuable: Can you explain the user benefit?
- Estimable: Is it clear enough to implement?
- Small: Could this be done in 1-3 days? If not, break it down.
- Testable: Can you write acceptance criteria?
Acceptance Criteria
Acceptance criteria define WHEN a story is complete. They should be:
- Specific: Clear, unambiguous conditions
- Measurable: Can be verified as pass/fail
- Complete: Cover the happy path AND edge cases
Format
Use checkbox format for easy verification:
## Acceptance Criteria
- [ ] User can request password reset with their email
- [ ] Reset link is sent to registered email only
- [ ] Reset link expires after 1 hour
- [ ] User sees error message for unregistered email
- [ ] User can set new password via reset link
- [ ] Old password no longer works after reset
Writing Good Criteria
Good criteria:
- Login form shows error for incorrect password
- Error message says "Invalid email or password" (not which is wrong)
- Account locks after 5 failed attempts
Bad criteria:
- Login works correctly (too vague)
- Errors are handled (not specific)
- Good UX (not measurable)
Breaking Down Large Features
Large features should be broken into stories sized for a single PR.
Splitting Strategies
By User Flow Step
- Registration → Login → Password Reset → Session Management
By Data Entity
- User Model → User API → User UI
By User Type
- End-user features → Admin features
By Complexity Layer
- Backend API → Frontend UI → Integration
Example: "User Authentication" Feature
Break into:
| Issue | Story | Dependencies |
|---|---|---|
| #1 | Database schema for users | None |
| #2 | User registration endpoint | #1 |
| #3 | User login endpoint | #1 |
| #4 | Session management | #3 |
| #5 | Password reset flow | #2, #3 |
Each issue is one PR's worth of work.
Issue Template
## User Story
As a [type of user],
I want [goal/desire],
So that [benefit/value].
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
## Technical Notes
[Architecture decisions, approach, or constraints]
## UI/UX Requirements
[Design specs, wireframes, or "None - backend only"]
## Dependencies
[List as "Depends on #X" or "None - can be worked independently"]
## Out of Scope
[Explicitly list what is NOT included to avoid scope creep]
Common Mistakes
Too Big
Bad: "As a user, I want a complete authentication system" Better: Split into registration, login, password reset, etc.
No User Value
Bad: "Refactor the database layer" Better: "As a developer, I want a normalized user schema so that queries are faster"
Vague Criteria
Bad: "Login should work well" Better: "User is redirected to dashboard after successful login"
Missing Edge Cases
Bad: Only happy path criteria Better: Include error states, empty states, boundary conditions
Hidden Dependencies
Bad: No mention of required prior work Better: "Depends on #1 (User model must exist first)"
Verification
Before finalizing a story, verify:
- Is the user clear? Who specifically benefits?
- Is the goal actionable? What exactly will they do?
- Is the value stated? Why does this matter?
- Are criteria testable? Can each be verified pass/fail?
- Is it sized right? One PR, not a week of work?
- Are dependencies explicit? What must exist first?
- Is scope bounded? What's explicitly excluded?