user-story-templates

name	user-story-templates
description	User story templates with acceptance criteria, story splitting, and INVEST criteria. Use when writing user stories, defining acceptance criteria, splitting large stories, or refining a backlog for sprint planning. Trigger on: 'write user stories for this feature', 'acceptance criteria', 'Given-When-Then', 'split this epic into stories', 'INVEST criteria'.

User Story Templates

Comprehensive templates and frameworks for writing effective user stories with clear acceptance criteria, enabling agile development teams to deliver value incrementally.

What is a User Story?

A user story is a concise description of a feature from the end-user's perspective. It follows the format: "As a [user], I want [goal], so that [benefit]."

Purpose:

• Communicate requirements from user perspective
• Enable incremental delivery
• Facilitate conversation and collaboration
• Support estimation and planning
• Guide testing and acceptance

When to Use This Skill

Auto-loaded by agents:

• requirements-engineer - For user story formats, epic breakdown, and spike stories

Use when you need:

• Breaking down features into user stories
• Writing acceptance criteria
• Planning sprints and iterations
• Communicating requirements to development teams
• Refining product backlogs
• Splitting large stories
• Validating story quality with INVEST criteria
• Estimating and prioritizing work

---

User Story Format

Basic Template

As a [user type/persona]
I want to [action/goal]
So that [benefit/value]

Example:

As a small business owner
I want to export my invoices as PDF
So that I can send professional-looking invoices to clients

Three Key Components

1. User Type/Persona (Who)

• Specific user segment or role
• Good: "free trial user", "team administrator", "mobile app user"
• Bad: "user" (too vague), "the system" (not a user)

2. Action/Goal (What)

• What the user wants to accomplish
• Good: "filter search results by date range", "receive email notifications"
• Bad: "have a button" (describes UI), "use the API" (describes implementation)

3. Benefit/Value (Why)

• Why the user wants this, what value it provides
• Good: "so that I can quickly find relevant information"
• Bad: "so that it works" (not a benefit), omitting "so that" entirely

For detailed guidance on each component, see assets/basic-user-story-template.md.

---

Ready-to-Use Templates

We provide copy-paste-ready templates for common story types:

Feature Stories

Use for: New features, enhancements, user-facing work Template: assets/feature-story-template.md

Includes:

• Full user story format
• Acceptance criteria checklist
• Definition of Done
• Story points and priority
• Dependencies tracking

---

Bug Fix Stories

Use for: Defects, regressions, user-reported issues Template: assets/bug-fix-story-template.md

Includes:

• Current vs expected behavior
• Steps to reproduce
• Environment details
• Severity levels
• Impact assessment

---

Technical Debt Stories

Use for: Refactoring, code improvements, infrastructure work Template: assets/technical-debt-story-template.md

Includes:

• Technical context
• Proposed solution
• Impact on performance/maintainability/scalability
• Risk assessment
• Business value justification

---

Spike/Research Stories

Use for: Time-boxed investigation, POCs, research tasks Template: assets/spike-research-story-template.md

Includes:

• Research questions
• Time box
• Deliverables
• Acceptance criteria for knowledge gained
• Next steps identification

---

Epic Breakdown

Use for: Breaking large initiatives into manageable stories Template: assets/epic-breakdown-template.md

Includes:

• Epic goal and value proposition
• Story sequencing
• Definition of Done (epic level)
• Timeline and dependencies
• Risk mitigation

---

Acceptance Criteria

Acceptance criteria define when a story is "done." Use one of three formats:

1. GIVEN-WHEN-THEN (BDD Style)

Best for: Complex workflows, state-dependent behavior, testing focus

GIVEN [precondition/context]
WHEN [action/event]
THEN [expected outcome]

Example:

GIVEN I'm on the login page
WHEN I enter valid email and password
THEN I'm redirected to my dashboard

2. Checklist Format

Best for: Simple features, quick validation, straightforward requirements

Acceptance Criteria:
- [ ] [Observable outcome 1]
- [ ] [Observable outcome 2]
- [ ] [Observable outcome 3]

Example:

- [ ] Export button appears on data table
- [ ] Clicking export generates CSV file
- [ ] CSV includes all visible columns
- [ ] CSV filename includes current date
- [ ] Export completes within 5 seconds for up to 10K rows

3. Rule-Based Format (MoSCoW)

Best for: Variable scope, prioritization needed, time-constrained sprints

Must: [Critical requirements]
Should: [Important but not critical]
May: [Nice to have]

Comprehensive guide: See references/invest-criteria-guide.md for deep dive on writing testable, specific criteria including error states, edge cases, and performance requirements.

---

Story Splitting

Large stories (>5 days or >8 points) should be split into smaller, deliverable pieces.

Common Splitting Patterns

1. Workflow Steps: Sequential process steps (e.g., checkout: cart → shipping → payment → confirmation)

2. CRUD Operations: Create → Read → Update → Delete

3. User Roles: Admin → Manager → Employee → Guest

4. Business Rules: Different variations of logic (e.g., discount types: percentage, fixed amount, BOGO)

5. Simple to Complex: MVP → Advanced features (progressive enhancement)

6. Happy Path vs Edge Cases: Success scenarios → Error handling

7. Data Variations: Different formats, sizes, types

8. Platform/Device: Desktop → Tablet → Mobile

9. Performance Tiers: 1-5 users → 6-20 users → 21-100 users

10. Interface vs API: Backend → Frontend → Integration

Best practice: Use vertical slicing (complete feature through all layers) vs horizontal slicing (one layer across many features).

Comprehensive guide: See references/story-splitting-guide.md for detailed examples, anti-patterns, and decision trees.

---

INVEST Criteria

Good user stories follow the INVEST principles:

I - Independent: Can be developed without dependency on other stories N - Negotiable: Details flexible, focuses on outcome not implementation V - Valuable: Delivers clear value to user or business E - Estimable: Team can estimate effort with reasonable confidence S - Small: Fits in one sprint (1-5 days) T - Testable: Clear acceptance criteria that can be verified

Quick INVEST Check

• Independent: Can this be built without waiting for other stories?
• Negotiable: Does it define outcome, not implementation?
• Valuable: Is the benefit clear and meaningful?
• Estimable: Can the team estimate this confidently?
• Small: Can it be completed in 1-5 days?
• Testable: Are acceptance criteria clear and verifiable?

If a story fails any INVEST criterion, it should be rewritten or split.

Comprehensive guide: See references/invest-criteria-guide.md for deep dive on each principle with examples, anti-patterns, and fixing strategies.

---

User Story Best Practices

Writing Clear Stories

DO:

• Focus on user value, not implementation
• Keep stories independent and testable
• Write from user's perspective
• Include clear acceptance criteria
• Size stories for 1-3 days of work

DON'T:

• Prescribe implementation ("use React hooks")
• Mix multiple features in one story
• Write from system's perspective
• Skip acceptance criteria
• Create epics disguised as stories

Good Example

As a free trial user
I want to see how many days remain in my trial
So that I can decide when to upgrade

Acceptance Criteria:
- [ ] Days remaining appears in header
- [ ] Warning shows when <7 days remain
- [ ] "Upgrade" CTA appears with countdown
- [ ] Counter updates daily at midnight

Bad Example

As the system
I want to implement a counter using React hooks
So that the trial days feature works

[No acceptance criteria]

---

Acceptance Criteria Best Practices

DO:

• Make criteria testable and observable
• Include happy path AND error states
• Specify performance requirements
• Cover edge cases
• Use numbers for specificity

Good Example:

- [ ] Search completes within 2 seconds for datasets <10K records
- [ ] Loading spinner shows while search is processing
- [ ] Error message appears if search fails
- [ ] No results message shows when query returns 0 items
- [ ] Search results highlight matching keywords

Bad Example:

- Search feature works
- UI looks good
- Performance is acceptable

---

Story Point Estimation

Modified Fibonacci Scale

• 1 point: Trivial change (1-2 hours)
• 2 points: Small change (half day)
• 3 points: Medium change (1 day)
• 5 points: Larger change (2-3 days)
• 8 points: Large change (3-5 days) - consider splitting
• 13 points: Epic, must be split

Estimation Guidelines

• Points represent complexity, not time
• Compare to reference stories ("this is like that export feature we built")
• Include testing and documentation in estimate
• Account for unknowns
• Split stories >8 points

---

Common Mistakes to Avoid

Too technical:

• Bad: "Implement REST API endpoint"
• Good: "Retrieve my order history via mobile app"

Too large:

• Bad: "Build entire checkout system"
• Good: "Enter shipping address during checkout"

Implementation-focused:

• Bad: "Add a button to the navbar"
• Good: "Access my account settings quickly"

Missing acceptance criteria:

• Bad: Only the story statement
• Good: Story + clear, testable acceptance criteria

Vague:

• Bad: "Make the app faster"
• Good: "Load dashboard in under 2 seconds"

---

Templates and References

Assets (Ready-to-Use Templates)

Copy-paste these for immediate use:

• assets/basic-user-story-template.md - Simple story format with guidance
• assets/feature-story-template.md - Full-featured story with DoD
• assets/bug-fix-story-template.md - Bug tracking and resolution
• assets/technical-debt-story-template.md - Technical improvements
• assets/spike-research-story-template.md - Time-boxed research
• assets/epic-breakdown-template.md - Epic to stories breakdown

References (Deep Dives)

When you need comprehensive guidance:

• references/story-splitting-guide.md - 10 splitting patterns with examples, anti-patterns, decision trees
• references/invest-criteria-guide.md - Writing testable criteria, all three formats, common mistakes
• references/invest-criteria-guide.md - Deep dive on each INVEST principle with examples and fixes

---

Quick Start

For new features:

1. Start with assets/feature-story-template.md
2. Fill in user type, goal, and benefit
3. Add acceptance criteria (use references/invest-criteria-guide.md if needed)
4. Verify INVEST criteria
5. Estimate story points
6. If >8 points, split using patterns from references/story-splitting-guide.md

For bugs:

1. Use assets/bug-fix-story-template.md
2. Document current vs expected behavior
3. Add reproduction steps
4. Include severity and impact
5. Write fix verification criteria

For research:

1. Use assets/spike-research-story-template.md
2. Define research questions
3. Set time box (critical!)
4. Specify deliverable
5. Include next steps in acceptance criteria

---

Troubleshooting

"My stories are too big to estimate": Apply the INVEST S (Small) test. If a story can't ship in one sprint, split it. Use the splitting patterns in references/story-splitting-guide.md -- split by workflow step, user type, data variation, or happy path vs. error handling.

"Developers say my acceptance criteria are unclear": Switch to Given-When-Then format. "Given [precondition], When [action], Then [outcome]" forces you to be specific. If you can't write the Given clause, you don't understand the starting state well enough.

"Every story feels like it depends on every other story": You're writing at the wrong level. Stories should be independently deliverable (the I in INVEST). If they can't be, you likely have an epic that needs decomposition, not a set of interdependent stories.

---

Related Skills

• prd-templates - PRD structure for the feature these stories belong to
• specification-techniques - Broader spec writing including non-functional requirements
• prioritization-methods - Prioritizing stories in the backlog

---

Key Principle: Great user stories are conversations, not contracts. They enable collaboration while providing enough structure to guide development, testing, and acceptance.