# User Stories

# User Stories: {{PROJECT_NAME}}

> **Project:** {{PROJECT_NAME}}
> **Version:** {{VERSION}}
> **Date:** {{DATE}}
> **Author:** {{AUTHOR}}
> **Status:** Draft | In Review | Approved
> **Reviewers:** {{REVIEWERS}}

## Document History
| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1     | {{DATE}} | {{AUTHOR}} | Initial draft |

---

<!-- GUIDANCE: User stories capture requirements from the user's perspective.
This document contains the full story backlog organized by Epic.
Individual story cards live in Mission Control (task system); this document is the
structured reference that feeds the backlog. -->

## 1. Epic Overview

<!-- GUIDANCE: Epics are large user stories that span multiple sprints.
Each epic should represent a meaningful business capability.
Stories within an epic deliver incremental value toward that capability. -->

| Epic ID | Epic Name | Business Goal | Story Count | Status | Target Release |
|---------|----------|--------------|-------------|--------|---------------|
| EP-01 | {{EPIC_NAME}} | {{BUSINESS_GOAL}} | {{COUNT}} | Backlog / In Progress | {{RELEASE}} |
| EP-02 | | | | | |
| EP-03 | | | | | |

---

## 2. Epic Templates

### Epic: EP-01 — {{EPIC_NAME}}

<!-- GUIDANCE: An epic describes a large feature or business area. It includes:
- The business goal it serves
- The persona(s) who benefit
- A narrative description
- The individual stories that break it down -->

**Epic Statement:**
As a **{{PERSONA}}**, I need **{{CAPABILITY}}** so that **{{BUSINESS_VALUE}}**.

**Business Goal:** {{BUSINESS_OBJECTIVE_REFERENCE}}
**Priority:** Must Have | Should Have | Could Have
**Estimated Size:** {{X}} story points (rough)
**Target Sprint(s):** Sprint {{X}} – Sprint {{Y}}

**Acceptance Criteria at Epic Level:**
- [ ] {{HIGH_LEVEL_CRITERION_1}}
- [ ] {{HIGH_LEVEL_CRITERION_2}}
- [ ] {{HIGH_LEVEL_CRITERION_3}}

**Stories in This Epic:**
- US-001: {{STORY_TITLE}}
- US-002: {{STORY_TITLE}}
- US-003: {{STORY_TITLE}}

---

## 3. Story Format Guide

<!-- GUIDANCE: Every story follows this format. Read before writing stories. -->

**Standard Story Format:**
```
As a [persona/role],
I want [feature/action],
So that [benefit/outcome].
```

**Acceptance Criteria Format (Given/When/Then):**
```
Given [a precondition that must be true],
When [the user performs an action],
Then [the expected outcome occurs].
```

**Key Principles:**
- Stories describe WHAT the user needs, not HOW to build it
- Each story must be independently valuable and testable
- Stories should be completable within a single sprint
- If a story takes > 8 story points, break it into smaller stories
- Acceptance criteria should be written as tests (they become test cases)

---

## 4. Story Backlog

<!-- GUIDANCE: Add all stories organized by Epic. Use the template for each story.
Copy the story block and fill in each field. Leave no field empty — use TBD if unknown. -->

### Epic EP-01: {{EPIC_NAME}}

---

#### US-001: {{STORY_TITLE}}

| Attribute | Value |
|-----------|-------|
| Epic | EP-01: {{EPIC_NAME}} |
| Priority | Must Have | Should Have | Could Have |
| Story Points | 1 | 2 | 3 | 5 | 8 |
| Sprint | {{SPRINT_NUMBER}} |
| Assigned To | {{AGENT/PERSON}} |
| Status | Backlog | Ready | In Progress | Review | Done |
| FR Reference | FR-{{XXX}} |
| BR Reference | BR-{{XXX}} |

**Story:**
As a **{{PERSONA}}**,
I want **{{ACTION/FEATURE}}**,
So that **{{BENEFIT/OUTCOME}}**.

**Context:**
{{ADDITIONAL_CONTEXT_THAT_HELPS_UNDERSTAND_THE_STORY}}

**Acceptance Criteria:**
- [ ] **Given** {{PRECONDITION}}, **when** {{USER_ACTION}}, **then** {{EXPECTED_RESULT}}
- [ ] **Given** {{PRECONDITION}}, **when** {{USER_ACTION}}, **then** {{EXPECTED_RESULT}}
- [ ] **Given** {{ERROR_CONDITION}}, **when** {{USER_ACTION}}, **then** {{ERROR_HANDLING}}

**Technical Notes:**
<!-- GUIDANCE: Optional — add only if there are specific implementation constraints or hints -->
- {{TECHNICAL_CONSTRAINT_OR_HINT}}

**UI/UX Notes:**
- Screen / component: {{SCREEN_NAME}}
- Design reference: {{FIGMA_LINK_OR_FILE}}
- Responsive behavior: {{NOTES}}

**Dependencies:**
- Blocked by: {{US-XXX | None}}
- Blocks: {{US-XXX | None}}
- External: {{THIRD_PARTY_DEPENDENCY | None}}

**Definition of Done:**
- [ ] Code complete and follows coding standards
- [ ] Unit tests written (≥ 80% coverage on new code)
- [ ] Code review approved by Tech Lead
- [ ] Merged to `develop`
- [ ] Deployed to staging
- [ ] All acceptance criteria manually verified
- [ ] No critical or high bugs open
- [ ] Documentation updated (if applicable)

---

#### US-002: {{STORY_TITLE}}

| Attribute | Value |
|-----------|-------|
| Epic | EP-01 |
| Priority | Must Have |
| Story Points | {{POINTS}} |
| Sprint | {{SPRINT}} |
| Assigned To | {{AGENT}} |
| Status | Backlog |
| FR Reference | FR-{{XXX}} |

**Story:**
As a **{{PERSONA}}**,
I want **{{ACTION}}**,
So that **{{BENEFIT}}**.

**Acceptance Criteria:**
- [ ] **Given** {{PRECONDITION}}, **when** {{USER_ACTION}}, **then** {{EXPECTED_RESULT}}
- [ ] **Given** {{PRECONDITION}}, **when** {{USER_ACTION}}, **then** {{EXPECTED_RESULT}}

**Dependencies:** Blocked by: {{US-001 | None}}

**Definition of Done:** _(same as standard DoD above)_

---

### Epic EP-02: {{EPIC_NAME}}

---

#### US-010: {{STORY_TITLE}}

| Attribute | Value |
|-----------|-------|
| Epic | EP-02 |
| Priority | Should Have |
| Story Points | {{POINTS}} |
| Sprint | {{SPRINT}} |
| Assigned To | {{AGENT}} |
| Status | Backlog |

**Story:**
As a **{{PERSONA}}**,
I want **{{ACTION}}**,
So that **{{BENEFIT}}**.

**Acceptance Criteria:**
- [ ] **Given** {{PRECONDITION}}, **when** {{USER_ACTION}}, **then** {{EXPECTED_RESULT}}

**Dependencies:** None

**Definition of Done:** _(standard DoD)_

---

## 5. Story Estimation Guide

<!-- GUIDANCE: Use this guide for consistent story point estimation.
Story points measure complexity + effort + uncertainty, NOT hours. -->

| Points | Complexity | Examples |
|--------|-----------|---------|
| 1 | Trivial | Update a label, fix a CSS bug, add a config option |
| 2 | Simple | Simple form field, read-only data display, static page |
| 3 | Moderate | CRUD for one entity, simple filter, email notification |
| 5 | Complex | Multi-step form, API integration, complex UI component |
| 8 | Very Complex | New module with CRUD + logic + UI + tests |
| 13+ | Too Large | Break into smaller stories |

**Planning Poker:** Use async estimation — each team member estimates independently, then compare and discuss outliers.

---

## 6. Definition of Ready Checklist

<!-- GUIDANCE: A story is "ready" to enter a sprint only when ALL of these are true.
Moving stories into sprints before they're ready is a leading cause of sprint failure. -->

Before a story can be added to a sprint, verify:

- [ ] Story is written in As a / I want / So that format
- [ ] Story has at least 2 acceptance criteria in Given/When/Then format
- [ ] Story has been estimated in story points
- [ ] Dependencies are identified and not blocking
- [ ] UI/UX design exists (or story is backend-only)
- [ ] Technical approach is understood (no major unknowns)
- [ ] Priority is assigned (MoSCoW)
- [ ] Story size is ≤ 8 points (or confirmed as a spike)
- [ ] Acceptance criteria are testable by QA
- [ ] FR reference documented

---

## 7. Story Breakdown Techniques

<!-- GUIDANCE: Use these techniques when a story is too large for one sprint. -->

| Technique | When to Use | How |
|-----------|------------|-----|
| **CRUD Split** | Create/Read/Update/Delete are all in one story | Split into 4 stories (View, Create, Edit, Delete) |
| **Happy Path First** | Story handles many edge cases | First story = happy path only; subsequent stories = edge cases |
| **Data Variations** | Story handles many data types | Split by data type or category |
| **Workflow Steps** | Multi-step process in one story | Split by step (Step 1 as standalone value, etc.) |
| **User Type Split** | Different users, different experiences | One story per user type |
| **Performance Deferred** | Core function + performance optimization mixed | Functional story first; performance story second |
| **UI + API Split** | Full-stack story too large | API story first; UI story depends on API story |

---

## 8. Story Mapping Visualization

<!-- GUIDANCE: Story mapping organizes stories on a 2D grid:
- Horizontal axis: user journey / workflow (left to right = sequence)
- Vertical axis: priority (top = MVP, bottom = later releases)
This helps plan MVP scope and identify gaps in the user journey. -->

```
USER JOURNEY:  [Discovery] → [Registration] → [Core Feature] → [Management] → [Reporting]

MVP           US-001         US-020           US-030           US-040           —
(Release 1)

Release 2     —              US-021           US-031           US-041           US-050

Release 3     —              —                US-032           US-042           US-051
```

> _Replace with actual story IDs mapped to user journey steps and release priority_

---

## 9. Backlog Summary

<!-- GUIDANCE: Keep this summary table updated. It provides a quick view of backlog health. -->

| Epic | Total Stories | Estimated Points | In Sprint | Done | Remaining |
|------|-------------|-----------------|-----------|------|-----------|
| EP-01: {{NAME}} | {{COUNT}} | {{POINTS}} | {{COUNT}} | {{COUNT}} | {{COUNT}} |
| EP-02: {{NAME}} | | | | | |
| **Total** | | | | | |

**Velocity (last sprint):** {{STORY_POINTS_COMPLETED}}
**Projected completion:** Sprint {{X}} ({{DATE}})

---

## Approval

| Role | Name | Date | Signature |
|------|------|------|-----------|
| Author | | | |
| Reviewer | | | |
| Business Analyst | | | |
| Product Owner | | | |
| AI Director (John) | | | |