| 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:
Bad criteria:
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?
