# User Story Template

Use this template when creating user story issues in GitHub Projects. Copy the structure below into the issue description.

---

## User Story: [Brief title from user perspective]

### Story

**As a** [specific user type/persona],
**I want** [goal or capability],
**So that** [benefit or value].

---

### Context

[Optional: Additional background or context that helps understand this story. Why is this needed? What problem does it solve?]

---

### Acceptance Criteria

[Define specific, testable conditions that must be met for this story to be considered complete]

> Format Option 1: Given-When-Then

- **Given** [context or starting state]
  **When** [action taken]
  **Then** [expected outcome]

- **Given** [another context]
  **When** [another action]
  **Then** [another outcome]

> Format Option 2: Simple Checklist

- [ ] Criterion 1: [Specific, observable outcome]
- [ ] Criterion 2: [Specific, observable outcome]
- [ ] Criterion 3: [Specific, observable outcome]

---

### Notes & Assumptions

[Optional: Any assumptions, constraints, or additional notes]

**Assumptions:**
- [Assumption 1]
- [Assumption 2]

**Constraints:**
- [Constraint 1]
- [Constraint 2]

**Out of Scope:**
- [What's NOT included in this story]

---

### Definition of Done

At story level, done means:

- [ ] All acceptance criteria met
- [ ] Code reviewed and merged
- [ ] Unit tests written and passing
- [ ] Integration tests passing (if applicable)
- [ ] Documented (user-facing docs, API docs, etc.)
- [ ] Tested in staging environment
- [ ] Acceptance confirmed by product owner/stakeholder

---

### Tasks

[Tasks will be created as child issues of this story. Link them here when created]

- Link to Task 1
- Link to Task 2
- [Tasks will be linked as children when created]

---

**Parent:** [Link to Epic Issue]
**Children:** [Task Issues will be linked here]

---

## Examples

### Example 1: Campaign Filtering

**As a** marketing manager,
**I want** to filter campaigns by date range,
**So that** I can analyze performance for specific time periods.

**Acceptance Criteria:**

- [ ] Date picker UI allows selection of start date and end date
- [ ] Only campaigns with activity within the selected date range are displayed
- [ ] If end date is before start date, system shows validation error
- [ ] "Clear filters" button returns to showing all campaigns
- [ ] Selected date range is preserved when navigating away and returning

**Notes:**
- Use native browser date pickers for best UX
- Default to "last 30 days" on initial page load

---

### Example 2: Password Reset

**As a** user who forgot my password,
**I want** to receive a password reset link via email,
**So that** I can regain access to my account.

**Acceptance Criteria:**

- **Given** I click "Forgot Password" on the login page
  **When** I enter my email address and submit
  **Then** I receive an email with a reset link within 2 minutes

- **Given** I click the reset link in the email
  **When** the link is less than 1 hour old
  **Then** I'm taken to a page to set a new password

- **Given** I enter a new password meeting requirements (8+ chars, etc.)
  **When** I submit the new password
  **Then** my password is updated and I'm redirected to login

- **Given** I click a reset link
  **When** the link is more than 1 hour old
  **Then** I see an error message saying the link expired

**Assumptions:**
- User email must already exist in system
- Reset links expire after 1 hour for security

**Out of Scope:**
- Multi-factor authentication (separate story)
- Account recovery without email access (separate story)

---

### Example 3: File Upload

**As a** content creator,
**I want** to upload image files to my media library,
**So that** I can use them in my posts and campaigns.

**Acceptance Criteria:**

- [ ] "Upload" button is clearly visible in media library
- [ ] Clicking "Upload" opens file browser allowing image selection
- [ ] Supported formats: JPG, PNG, GIF, WebP (max 10MB per file)
- [ ] Upload progress indicator shows during upload
- [ ] On success, uploaded image appears in media library immediately
- [ ] On failure (wrong format, too large), clear error message is shown
- [ ] Multiple files can be selected and uploaded at once

**Technical Notes:**
- Images should be automatically resized/optimized on server
- Store originals and generate thumbnails

---

## INVEST Check

Before finalizing a story, verify it meets INVEST criteria:

- [ ] **Independent**: Can be completed without depending on other stories
- [ ] **Negotiable**: Details are discussable, not fixed implementation
- [ ] **Valuable**: Delivers clear value to users or stakeholders
- [ ] **Estimable**: Team can reasonably estimate size/effort
- [ ] **Small**: Fits within a single iteration (1-5 days)
- [ ] **Testable**: Has clear acceptance criteria that can be verified

If any criteria aren't met, refine the story before committing to it.