<< All versions
Skill v1.0.1
currentAutomated scan100/100b33eep/claude-code-setup/user-stories
2 files
──Details
PublishedMay 25, 2026 at 01:42 AM
Content Hashsha256:d29777a056e641de...
Git SHA7e8cc42fb508
Bump Typepatch
──Files
Files (1 file, 6.1 KB)
SKILL.md6.1 KBactive
SKILL.md · 177 lines · 6.1 KB
version: "1.0.1" name: user-stories description: Write INVEST-compliant user stories with Given-When-Then acceptance criteria. Use when writing user stories, creating acceptance criteria, or during /design Step 4. type: command source: Adapted from https://github.com/alirezarezvani/claude-skills/tree/main/product-team/agile-product-owner by alirezarezvani (MIT License)
User Stories
Write high-quality, INVEST-compliant user stories with testable acceptance criteria.
User Story Template
As a [persona],I want to [action/capability],So that [benefit/value].
Example:
As a marketing manager,I want to export campaign reports to PDF,So that I can share results with stakeholders who don't have system access.
Story Types
| Type | Template | Example | |
|---|---|---|---|
| Feature | As a [persona], I want to [action] so that [benefit] | As a user, I want to filter search results so that I find items faster | |
| Improvement | As a [persona], I need [capability] to [goal] | As a user, I need faster page loads to complete tasks without frustration | |
| Bug Fix | As a [persona], I expect [behavior] when [condition] | As a user, I expect my cart to persist when I refresh the page | |
| Enabler | As a developer, I need to [technical task] to enable [capability] | As a developer, I need to implement caching to enable instant search |
Persona Reference
| Persona | Typical Needs | Context | |
|---|---|---|---|
| End User | Efficiency, simplicity, reliability | Daily feature usage | |
| Administrator | Control, visibility, security | System management | |
| Power User | Automation, customization, shortcuts | Expert workflows | |
| New User | Guidance, learning, safety | Onboarding |
Adapt personas to your project. Use specific names when possible (e.g., "store owner" instead of "end user").
INVEST Criteria
Validate every story before adding it to the backlog:
| Criterion | Question | Pass If... | |
|---|---|---|---|
| Independent | Can this be developed without other uncommitted stories? | No blocking dependencies | |
| Negotiable | Is the implementation flexible? | Multiple approaches possible | |
| Valuable | Does this deliver user or business value? | Clear benefit in "so that" | |
| Estimable | Can the team estimate this? | Understood well enough to size | |
| Small | Can this complete in one iteration? | Reasonably scoped | |
| Testable | Can we verify this is done? | Clear acceptance criteria |
Acceptance Criteria
Given-When-Then Template
Given [precondition/context],When [action/trigger],Then [expected outcome].
Examples:
Given the user is logged in with valid credentials,When they click the "Export" button,Then a PDF download starts within 2 seconds.Given the user has entered an invalid email format,When they submit the registration form,Then an inline error message displays "Please enter a valid email address."Given the shopping cart contains items,When the user refreshes the browser,Then the cart contents remain unchanged.
AC Checklist
Each story should include criteria for applicable categories:
| Category | Example | |
|---|---|---|
| Happy Path | Given valid input, When submitted, Then success message displayed | |
| Validation | Should reject input when required field is empty | |
| Error Handling | Must show user-friendly message when API fails | |
| Performance | Should complete operation within 2 seconds | |
| Accessibility | Must be navigable via keyboard only |
Not every category applies to every story. Use judgment.
Minimum Criteria by Story Size
| Size | Minimum AC Count | |
|---|---|---|
| Small (trivial) | 2-3 criteria | |
| Medium | 4-6 criteria | |
| Large | 5-8 criteria | |
| Too large | Split the story |
INVEST Failure Patterns
| Criterion | Red Flag | Fix | |
|---|---|---|---|
| Independent | "After story X is done..." | Combine stories or resequence | |
| Negotiable | Specific implementation in story | Focus on outcome, not solution | |
| Valuable | No "so that" clause | Add benefit statement | |
| Estimable | Team says "no idea" | Spike first, then story | |
| Small | Too large to finish in one iteration | Split into smaller stories | |
| Testable | "System should be better" | Add measurable criteria |
Story Splitting
When a story is too large, split using one of these techniques:
| Technique | Example | |
|---|---|---|
| By workflow step | "Create order" -> "Add items" + "Apply discount" + "Submit order" | |
| By persona | "User dashboard" -> "Admin dashboard" + "Member dashboard" | |
| By data type | "Import data" -> "Import CSV" + "Import Excel" | |
| By operation | "Manage users" -> "Add user" + "Edit user" + "Delete user" | |
| Happy path first | "Full feature" -> "Basic flow" + "Error handling" + "Edge cases" |
Common Antipatterns
Story Antipatterns
| Antipattern | Example | Fix | |
|---|---|---|---|
| Solution story | "Implement React component" | "Display user profile information" | |
| Compound story | "Create, edit, and delete users" | Split into three stories | |
| Missing persona | "The system will..." | "As an admin, I want to..." | |
| No benefit | "I want to see a button" | Add "so that [benefit]" | |
| Too vague | "Improve performance" | "Reduce page load to <2 seconds" | |
| Technical jargon | "Implement Redis caching" | "Enable instant search results" |
Acceptance Criteria Antipatterns
| Antipattern | Example | Fix | |
|---|---|---|---|
| Too vague | "Works correctly" | Specific Given-When-Then | |
| Implementation details | "Use PostgreSQL query" | Focus on outcome | |
| Missing unhappy path | Only success scenario | Add error cases | |
| Untestable | "User is happy" | Measurable behavior | |
| Too many | 15+ criteria | Split the story |
References
- Based on agile-product-owner by alirezarezvani (MIT License)
- Adapted and reduced to user story focus only (no sprint planning, velocity tracking, or epic breakdown)