# User Stories

> Write user stories with acceptance criteria following INVEST principles

- Skill: `bromso/user-stories` (Agent Skill)
- Install (CLI): `npx skillmds@latest add bromso/user-stories`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bromso/user-stories/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bromso (https://skillmd.com/u/bromso)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bromso/user-stories

---


# User Stories

Write detailed user stories for "$ARGUMENTS". Use the "As a / I want / So that" format, add Given/When/Then acceptance criteria, validate against the INVEST checklist, and split stories that are too large.

## Prerequisites

Check that `.project/$ARGUMENTS/00-initiate.md` exists. If it does not, tell the user to run an Initiate skill first (e.g., project-charter) and stop.

If the user passes `--skip-checks`, skip the prerequisite check and log the skip to `.project/$ARGUMENTS/skip-log.md` with a timestamp and reason.

## Process

1. **Read existing context:**
   - Read `.project/$ARGUMENTS/00-initiate.md` for charter and stakeholder context
   - Read `.project/$ARGUMENTS/01-plan.md` if it exists (for vision, roadmap, and backlog)
   - Read `plugins/project-management/shared/user-story-template.md` for the standard story format
   - Read `plugins/project-management/shared/scrum-guide.md` for Scrum alignment

2. **Write stories in standard format:**
   - For each story (from the backlog, or created fresh if no backlog exists):
     - **As a** [specific persona — not just "user"], **I want** [concrete action], **so that** [measurable benefit]
   - Use personas identified in stakeholder mapping or charter
   - Ensure the "so that" clause expresses real user or business value
   - Avoid implementation details in the story statement — focus on the need, not the solution

3. **Add Given/When/Then acceptance criteria:**
   - Write 2-5 acceptance criteria per story using the Gherkin format:
     - **Given** [precondition or context]
     - **When** [action performed by the user]
     - **Then** [expected observable outcome]
   - Cover the happy path, key edge cases, and error scenarios
   - Make criteria specific and testable — avoid vague terms like "should work properly"
   - Include data examples where relevant (e.g., "Given a cart with 3 items totaling $45.00")

4. **Validate against INVEST checklist:**
   - For each story, check:
     - **Independent** — can be developed without depending on another story
     - **Negotiable** — details can be discussed; it is not a rigid specification
     - **Valuable** — delivers clear value to the user or business
     - **Estimable** — the team can reasonably estimate the effort
     - **Small** — can be completed within a single sprint
     - **Testable** — acceptance criteria are concrete enough to verify
   - Flag stories that fail any INVEST criterion and note what needs to change

5. **Add story details:**
   - **Priority:** Must / Should / Could / Won't (from backlog prioritization)
   - **Labels:** feature, bug, tech-debt, spike + component labels (frontend, backend, etc.)
   - **Dependencies:** other stories or external dependencies
   - **Size estimate:** story points using Fibonacci scale (1, 2, 3, 5, 8, 13) if known
   - **Epic:** parent epic from the backlog

6. **Split stories that are too large:**
   - Any story estimated at >13 points needs splitting
   - Splitting strategies:
     - **By workflow step:** split a multi-step process into individual steps
     - **By data variation:** handle one data type first, add others later
     - **By operation:** split CRUD into separate Create, Read, Update, Delete stories
     - **By persona:** if multiple users benefit, split by user type
     - **By acceptance criteria:** each complex criterion becomes its own story
   - After splitting, re-validate each new story against INVEST

7. **Write the artifact** — append to `.project/$ARGUMENTS/01-plan.md` under a `## User Stories` section:
   - **Stories** — each story with full format: statement, acceptance criteria, INVEST status, details
   - **Split Log** — stories that were split, the strategy used, and resulting stories
   - **INVEST Violations** — any remaining violations with notes on resolution
   - **Story Count Summary** — total stories, by priority, by epic, by size

## Output

User stories appended to `.project/$ARGUMENTS/01-plan.md`. Present a summary highlighting:
- Total number of stories written
- Stories passing all INVEST criteria vs. those with violations
- Stories that were split and why
- Distribution by priority and size estimate