Create Agile-style user stories with acceptance criteria.
User Story Format
## US-XXX: [Short Title]
**As a** [type of user/persona],
**I want** [goal/desire],
**So that** [benefit/value].
### Acceptance Criteria
- [ ] AC-1: Given [context], when [action], then [outcome]
- [ ] AC-2: Given [context], when [action], then [outcome]
### Notes
- [Additional context]
- [Dependencies]
## Workflow
1. **Gather Context**
- If argument provided, analyze description
- If `--interactive`, guide through story creation
2. **Identify User**
- Spawn `spec-author userstory` agent
- Define the persona:
- Who is the user?
- What is their goal?
- What pain point do they have?
3. **Define the Want**
- Focus on goal, not solution
- "I want to find products" not "I want a search box"
4. **Articulate Value**
- Connect to business value
- Save time, increase revenue, reduce risk
5. **Write Acceptance Criteria**
- Use Given/When/Then format
- Cover happy path and edge cases
6. **Validate with INVEST**
- Independent, Negotiable, Valuable
- Estimable, Small, Testable
- Score must be ≥ 7
7. **Output**
- Display formatted story
- Suggest splitting if too large
## INVEST Criteria
| Criterion | Question | Score |
| --- | --- | --- |
| Independent | Can be delivered alone? | 0-2 |
| Negotiable | Describes what, not how? | 0-2 |
| Valuable | Delivers user/business value? | 0-2 |
| Estimable | Team can estimate effort? | 0-2 |
| Small | Fits in one sprint? | 0-2 |
| Testable | Has clear pass/fail criteria? | 0-2 |
**Threshold:** Score 7+ to proceed, otherwise split or refine.
## Arguments
- `$ARGUMENTS` - Feature description
- `--interactive` - Step-by-step guided authoring
- `--persona` - Specify user persona
- `--append` - Append to specification file
## Examples
```bash
# From description
/spec-driven-development:userstory-author "Search for products by keyword"
# Interactive mode
/spec-driven-development:userstory-author --interactive
# With specific persona
/spec-driven-development:userstory-author "View order history" --persona "returning customer"
# Append to spec
/spec-driven-development:userstory-author "Reset password" --append .specs/auth/spec.md
Story Splitting Patterns
If INVEST score is low, the agent suggests splitting:
Split by User Type
Before: "As a user, I want to see a dashboard"
After:
- "As an admin, I want to see system metrics dashboard"
- "As a sales rep, I want to see my pipeline dashboard"
Split by Workflow Steps
Before: "As a user, I want to complete checkout"
After:
- "As a user, I want to review my cart"
- "As a user, I want to enter shipping info"
- "As a user, I want to confirm my order"
Split by Operations (CRUD)
Before: "As a user, I want to manage my profile"
After:
- "As a user, I want to view my profile"
- "As a user, I want to update my profile"
- "As a user, I want to delete my account"
Output Example
## US-001: Search Products by Keyword
**As a** shopper,
**I want** to search for products using keywords,
**So that** I can quickly find items I'm interested in purchasing.
### Acceptance Criteria
- [ ] AC-1: Given I am on the product listing page, when I enter "laptop"
in the search box and press enter, then I see products containing
"laptop" in title or description
- [ ] AC-2: Given I have searched for "laptop", when results are displayed,
then I see the result count and results are sorted by relevance
- [ ] AC-3: Given I search for a term with no matches, when results are
displayed, then I see "No products found" message with suggestions
### INVEST Score: 10/12
| I | N | V | E | S | T |
| - | - | - | - | - | - |
| 2 | 2 | 2 | 2 | 1 | 1 |
**Notes:**
- S/T slightly reduced due to search relevance complexity
- Consider spike for search ranking algorithm
### Dependencies
- Product catalog must be indexed
- Search infrastructure required
### Priority
Must (core shopping functionality)
Related Commands
/spec-driven-development:gherkin-author- Create Gherkin scenarios/spec-driven-development:ears-author- Create EARS requirements/spec-driven-development:specify- Generate full specification