User Story Format

---
name: user-story-format
description: Reference only — the single definition of this project's user-story body (story, Gherkin ACs, test scenarios, Missing Information, DoD) and its AC/scenario rules. Read by user-story-enhancer (WAY 6) and benchmark-gap-story-writer (WAY 8) so stories they write stay identical in shape and WAY 6 can re-score WAY 8's output. Not a workflow on its own.
---

# user-story-format

Agents that write user stories `Read` this file and follow it exactly. When
the format changes, change it here only.

## Story body

```markdown
## User Story

As a <actor>, I want <goal> so that <business value>.

**Constraints:**
- <constraint>
- ...

---

## Acceptance Criteria

| # | Title | Priority |
|---|-------|----------|
| AC-01 | <title> | `must` |
| ... | | |

<details>
<summary>View full Gherkin scenarios</summary>

**AC-01 — <title>** `must`
- **Given** <precondition>
- **When** <action>
- **Then** <observable, assertable outcome>

...

</details>

---

## Test Scenarios

| Type | Description |
|------|-------------|
| `happy_path` | ... |
| `edge_case` | ... |
| `negative` | ... |
| `boundary` | ... |
| `security` | ... |
| `performance` | ... |

---

## Missing Information

- <open question that blocks writing tests>
- ...

---

## Definition of Done

- [ ] <measurable completion criterion>
- [ ] Regression tests generated by `test-writer` and passing
- ...
```

Writers put their own header block **above** `## User Story`:
- `user-story-enhancer` (WAY 6) titles the section `## Enhanced User Story` instead of `## User Story`, and appends the original body in a `<details><summary>Original story (preserved)</summary>` block after the DoD
- `benchmark-gap-story-writer` (WAY 8) adds `# US-<n> — <title>` plus the **Gap source / Target today / Priority · Effort** lines

Every story body ends with the Output Watermark footer from `CLAUDE.md`.

## Acceptance criteria rules
- Gherkin Given / When / Then
- Cover: main happy path, every variant mentioned, error flows, edge cases, and non-functional requirements if stated
- At least one negative/failure path per story
- "Then" must be concrete, observable, and assertable. Never "the system should work correctly"
- Priority: `must` for core flows, `should` for important variants, `could` for nice-to-haves
- Number from AC-01 sequentially. `test-writer` traces tests back to these IDs (`**Covers:** AC-01`), so never renumber existing ACs on a re-run. Append new ones instead

## Test scenario types
- `happy_path`: the primary success flow, no deviations
- `edge_case`: valid but extreme input or state
- `negative`: invalid input or unauthorized action
- `boundary`: values at or just beyond defined limits
- `security`: auth bypass, injection, data exposure attempts
- `performance`: load, concurrency, or latency under realistic conditions

## Missing Information
Questions that block writing tests, one per line. An empty section means
"nothing blocking", so write `- none` rather than deleting the heading.
`e2e-session` and `write-tests` stop and ask the user while any question here
is unanswered.