writing-user-stories
Creates INVEST-compliant user stories with acceptance criteria. Use when capturing requirements, defining backlog items, or breaking down features.
When & Why to Use This Skill
This Claude skill automates the creation of high-quality, INVEST-compliant user stories complete with detailed acceptance criteria. It streamlines the requirements gathering process by ensuring every feature is independent, negotiable, valuable, estimable, small, and testable, helping product teams maintain a clean and actionable backlog while adhering to Agile best practices.
Use Cases
- Requirement Capture: Quickly transform vague feature ideas into structured user stories during initial product discovery and planning phases.
- Backlog Refinement: Efficiently break down complex epics into smaller, sprint-ready stories that fit within a single development cycle.
- Quality Assurance Alignment: Generate clear 'Given-When-Then' acceptance criteria to ensure developers and QA teams have a shared, testable understanding of feature requirements.
- Standardizing Documentation: Maintain a consistent format and naming convention across all project requirements using automated templates and sequential ID tracking.
- Technical Debt Reduction: Audit and rewrite existing vague requirements into professional, INVEST-compliant stories to improve team velocity and estimation accuracy.
| name | writing-user-stories |
|---|---|
| description | Creates INVEST-compliant user stories with acceptance criteria. Use when capturing requirements, defining backlog items, or breaking down features. |
User Story Writing
Create user stories meeting INVEST criteria.
Execution Requirements
- Use
templates/user-story.mdtemplate - Validate against INVEST criteria before completing
- Include 2-5 acceptance criteria
- Replace all
[bracketed placeholders] - Assign Story ID using next sequential number
Mode Detection
CREATE: No existing story path → Copy template, generate next ID, fill sections
EDIT: Path provided → Read existing, preserve ID, update as requested
User Story Format
As a [type of user],
I want [goal/desire],
So that [benefit/value].
Example:
As a registered customer,
I want to save items to a wishlist,
So that I can purchase them later without searching again.
Required Elements
Title - Short, descriptive. "Wishlist - Add Items" not "User feature for saving stuff"
User Story Statement - Who (role), What (goal), Why (value)
Acceptance Criteria - Specific, testable conditions with Given-When-Then or checklist format
INVEST Criteria
| Criterion | Meaning |
|---|---|
| Independent | Develop in any order |
| Negotiable | Details discussable |
| Valuable | Delivers user/business value |
| Estimable | Team can size it |
| Small | Fits in one sprint |
| Testable | Clear acceptance criteria |
Acceptance Criteria Formats
Given-When-Then (preferred):
- [ ] Given [precondition], When [action], Then [result]
Checklist:
- [ ] User can [action with measurable outcome]
Writing Guidelines
Be specific about user roles: "premium subscriber" not "user"
Focus on outcomes: "export my data" not "a button"
State the benefit: "analyze in Excel" not "click it"
Story Splitting
Split large stories by: workflow steps, business rules, data variations, user roles, or CRUD operations.
Anti-Patterns
Do not write technical stories ("As a developer..."). Do not combine multiple features. Do not describe implementation. Do not omit the value clause. Do not use vague criteria.
Story vs Task vs Bug
| Type | Purpose |
|---|---|
| Story | New user-facing capability |
| Task | Technical work, no direct user value |
| Bug | Fix broken behavior |
Directory Structure
stories/
├── US-001-brief-description.md
├── US-002-brief-description.md
└── archive/
Create stories/ if needed. Scan for existing US-*.md files, find highest number, increment, pad to 3 digits.
Template
Use templates/user-story.md for all new stories.
Output
After creating/editing, report: file path, Story ID, acceptance criteria count, any INVEST concerns.