# User Stories

User stories describe value in context. They do not replace detailed rules. Every P0 story needs acceptance scenarios, permissions, data effects, edge cases, and a linked test.

[Kit README](README.md) · [Project Overview](Project%20Overview.md) · [PRD](Full%20PRD%20Template.md) · [Master Build Prompt](Master%20Build%20Prompt.md) · [Completion Checklist](Project%20Completion%20Checklist.md)

## Story Map

| ID | User | Story Outcome | Priority | Evidence |
| --- | --- | --- | --- | --- |
| US-01 | prospective customer comparing an offer | use responsive header and navigation to understand the offer within ten seconds | P0 | [TEST ID] |
| US-02 | returning visitor looking for a resource | use purpose-built page templates to reach any primary page in two navigation actions | P0 | [TEST ID] |
| US-03 | site owner publishing or reviewing content | use contact form with validation and spam controls to submit a contact request with clear confirmation | P0 | [TEST ID] |
| US-04 | prospective customer comparing an offer | use SEO metadata and structured content to understand the offer within ten seconds | P1 | [TEST ID] |
| US-05 | returning visitor looking for a resource | use analytics with consent-aware events to reach any primary page in two navigation actions | P1 | [TEST ID] |
| US-06 | site owner publishing or reviewing content | use accessible keyboard and screen-reader behavior to submit a contact request with clear confirmation | P1 | [TEST ID] |

## Story Template

~~~text
ID: US-[NN]
As a [SPECIFIC USER IN CONTEXT],
when [TRIGGER OR PRECONDITION],
I want to [ACTION],
so that [MEASURABLE OUTCOME].

Business rules: [RULES]
Permissions: [WHO MAY VIEW/CREATE/CHANGE/DELETE]
Data effects: [READS AND WRITES]
Out of scope: [BOUNDARY]
Analytics: [EVENT OR “NONE”]
~~~

## Acceptance Scenarios

### Happy Path

- **Given** [VALID STARTING STATE]
- **When** [USER ACTION]
- **Then** [VISIBLE RESULT]
- **And** [PERSISTED OR EXTERNAL EFFECT]

### Invalid Input

- **Given** [STATE]
- **When** [INVALID OR INCOMPLETE ACTION]
- **Then** the specific issue is explained, focus moves appropriately, and valid input remains.

### Unauthorized or Unavailable

- **Given** [INSUFFICIENT PERMISSION OR FAILED DEPENDENCY]
- **When** [ACTION]
- **Then** no protected change occurs, the product does not imply success, and a safe next step is offered.

### Repeat or Retry

- **Given** the action may be repeated because of refresh, timeout, or reconnect
- **When** the same valid request is received
- **Then** behavior is idempotent or the user is warned before duplication.

## Story Readiness Checklist

- [ ] One user and one outcome are clear.
- [ ] The story can be completed and verified independently.
- [ ] Business rules, permissions, states, and data effects are documented.
- [ ] Acceptance criteria are observable rather than subjective.
- [ ] Relevant website risks such as unclear positioning are addressed.
- [ ] The story links to a test and a PRD requirement.