| name | user-story |
| description | Drafts and finalizes user stories with Gherkin acceptance criteria for bounded contexts. Use when acceptance criteria for a feature are agreed during design sessions, or to extract stories from existing documents. Trigger whenever the user says "user story", "as a user", "acceptance criteria", or asks to define what a feature needs to do. Validates stories against INVEST criteria. Outputs structured stories with Gherkin to docs/bounded-contexts/{BC}/user-stories.md. |
User Story
Captures user stories as they emerge and produces INVEST-validated stories with Gherkin acceptance criteria.
Output Format
Each bounded context gets its own file:
docs/bounded-contexts/{BoundedContext}/user-stories.md
## [DRAFT] User Stories — {BoundedContext}
### US-{N}: {Story Title}
**As a** {role}
**I want** {feature/capability}
**So that** {business value}
**Acceptance Criteria:**
- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] {Criterion 3 (minimum)}
**Gherkin:**
```gherkin
Feature: {Story Title}
Scenario: {Criterion 1 scenario}
Given {context}
When {action}
Then {outcome}
INVEST: Independent ✅ | Negotiable ✅ | Valuable ✅ | Estimable ✅ | Small ✅ | Testable ✅
Mark as `[DRAFT]` until finalization. Remove markers only during the finalization pass.
## Mode 0 — Extraction from Documents
Use when existing documents are provided.
1. Read all input documents
2. Identify every user-facing feature, capability, or workflow
3. Draft a user story entry for each feature — use `[OPEN]` for missing acceptance criteria
4. Identify the bounded context each story belongs to
5. Write draft files to `docs/bounded-contexts/{BC}/user-stories.md`
6. Announce: "Extracted N user stories — M gaps marked [OPEN]."
## Mode 1 — Progressive Capture (During Sessions)
Use as soon as acceptance criteria for a feature are agreed during design interrogation.
When criteria are agreed:
1. Create `docs/bounded-contexts/{BC}/user-stories.md` if it does not exist
2. Write the draft story entry (criteria captured, Gherkin `[OPEN]`)
3. Announce: "📝 Draft user story logged to `docs/bounded-contexts/{BC}/user-stories.md`."
## Mode 2 — Finalization
Run when interrogation is complete.
1. Read all draft user story files
2. Complete all `[OPEN]` acceptance criteria — resolve or defer explicitly
3. Add Gherkin scenarios traced to every acceptance criterion
4. Validate each story against INVEST:
- **Independent** — can be delivered without depending on another story
- **Negotiable** — details can still be discussed
- **Valuable** — delivers clear value to the actor
- **Estimable** — the team can estimate effort
- **Small** — completable within one sprint
- **Testable** — acceptance criteria are unambiguous and verifiable
5. Ensure minimum 3 acceptance criteria per story
6. Ensure all terms match the finalized `UBIQUITOUS_LANGUAGE.md`
7. Remove all `[DRAFT]` markers
8. Write the finalized files
Announce:
> ✅ User stories finalized — N stories, M Gherkin scenarios, all INVEST-validated.
