user-stories
Scannednpx machina-cli add skill b33eep/claude-code-setup/user-stories --openclawFiles (1)
SKILL.md
6.1 KB
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)
Source
git clone https://github.com/b33eep/claude-code-setup/blob/main/skills/user-stories/SKILL.mdView on GitHub Overview
This skill helps you craft high-quality, INVEST-compliant user stories using the As a [persona], I want to [action], So that [benefit] template. It emphasizes Given-When-Then acceptance criteria, story types (Feature, Improvement, Bug Fix, Enabler), and persona-driven context to deliver clear, testable backlog items.
How This Skill Works
Draft the story using the standard template and select a story type. Validate each story against the INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable) and attach a Given-When-Then acceptance criteria section along with an AC checklist that covers categories such as Happy Path, Validation, Error Handling, Performance, and Accessibility. Adapt personas to your project and reference design step timing, such as Design Step 4, when writing stories.
When to Use It
- At project kick-off to convert requirements into INVEST-compliant stories
- When specifying acceptance criteria for backlog items
- During design discussions or design Step 4 to clarify behavior
- When collaborating with product owners to validate value and scope
- When estimating backlog items and planning sprints
Quick Start
- Step 1: Write the story using the template: As a [persona], I want to [action], So that [benefit]
- Step 2: Validate with INVEST criteria and ensure the story is independent, negotiable, valuable, estimable, small, and testable
- Step 3: Create Given-When-Then acceptance criteria and build the AC checklist with categories such as Happy Path, Validation, Error Handling, Performance, and Accessibility
Best Practices
- Center each story on a clear persona and the value it delivers
- Keep stories independent, small, and estimable to fit a single iteration
- Use the As a [persona], I want to [action], So that [benefit] template plus Given-When-Then criteria
- Build an AC checklist with categories: Happy Path, Validation, Error Handling, Performance, Accessibility
- Split overly large stories using the Minimum Criteria by Story Size guidance to avoid Too large items
Example Use Cases
- 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
- As a user, I want to filter search results so that I find items faster
- As a user, I need faster page loads to complete tasks without frustration
- As a user, I expect my cart to persist when I refresh the page
- As a developer, I need to implement caching to enable instant search
Frequently Asked Questions
Add this skill to your agents
