User Story Authoring

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 userstory-author 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

# 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