user-story-writer

User Story Writer Skill

This skill produces production-ready user stories from a feature brief, PRD section, or verbal description. Each story follows the standard format with a clear who/what/why, behavioural acceptance criteria in Given/When/Then format, edge cases, and definition of done. Output is ready to paste into Jira, Linear, or your planning tool.

Required Inputs

Ask the user for these if not provided:

• Feature or change to break into stories — paste the brief, PRD section, or describe the feature
• User types / personas involved (e.g. admin, end user, guest, API consumer)
• Scope — are we writing one story or decomposing an epic into a full set of stories?
• Acceptance criteria format preference — Given/When/Then, bullet checklist, or both?
• Technical constraints or notes — anything the engineering team has flagged that should shape the stories

Output Structure

For each story:

---

Story: [Short title — verb + noun, e.g. "Filter search results by date range"]

Epic: [Parent epic name — e.g. "Advanced Search"]

Story ID: [Jira/Linear ID — leave blank if not yet created]

Priority: [P1 / P2 / P3]

Story points: [Leave blank — for engineering to estimate]

---

User Story

> As a [specific user type — not "user"],

> I want to [concrete action they want to take],

> So that [the outcome they achieve — business value, not feature description].

Example:

> As an account manager,

> I want to filter my client list by last contact date,

> so that I can quickly identify clients I haven't spoken to in over 30 days and prioritise outreach.

---

Context

[1–3 sentences of context that aren't in the user story itself: when does this story matter, what triggers the need, how does it fit into a larger flow. This helps engineers understand why before they ask.]

---

Acceptance Criteria

Format: Given / When / Then

Each criterion tests one specific behaviour. Write one GWT per observable outcome — not one GWT for the whole feature.

AC1: [Short name for this criterion]

Given [starting state or context]
When [user action]
Then [observable system behaviour]

AC2: [Short name]

Given [...]
When [...]
Then [...]

AC3: [Short name]

Given [...]
When [...]
Then [...]

---

Edge Cases

[List scenarios that are non-obvious but must be handled. These become additional ACs or notes to engineering.]

• [ ] [Edge case 1]: [e.g. User applies a date filter that returns 0 results — show empty state with clear messaging and a "clear filters" action]
• [ ] [Edge case 2]: [e.g. User has >10,000 clients — filter must not degrade load time >200ms]
• [ ] [Edge case 3]: [e.g. Date filter persists across page refresh — or explicitly should not if that's the decision]
• [ ] [Permission edge case]: [e.g. Read-only users can see the filter but cannot save filter presets]

---

Out of Scope

[Explicitly state what this story does NOT cover — prevents scope creep and clarifies where the next story begins.]

• Saving and sharing filter presets (separate story — see [Story X])
• Bulk actions on filtered results
• Exporting filtered client list to CSV

---

Definition of Done

• [ ] Acceptance criteria all pass
• [ ] Edge cases handled (or explicitly deferred with a new ticket raised)
• [ ] Unit tests written for each AC
• [ ] Works on mobile viewport (if applicable)
• [ ] Accessibility: keyboard navigable and screen-reader compatible
• [ ] Error states are handled and copy approved
• [ ] Product and design have reviewed in staging
• [ ] No console errors in production build

---

Epic Decomposition Template

If the user provides an epic or feature brief, decompose it into a full set of stories before writing them:

Epic: [Name]

Goal: [What outcome does completing this epic achieve?]

Stories:

| # | Story | Notes | Dependencies |

|---|---|---|---|

| 1 | [Core happy path story — the simplest version of the feature that delivers value] | | |

| 2 | [Validation / error handling story] | | Depends on #1 |

| 3 | [Edge case or power user story] | | Depends on #1 |

| 4 | [Admin or configuration story] | | |

| 5 | [Performance or scale story — if applicable] | | Depends on #1 |

Suggested sprint order: [Which stories are P1 for MVP? Which can follow in a later sprint?]

---

Common Story Anti-Patterns — and Fixes

Use these to review stories before handing to engineering:

| Anti-pattern | Example | Fix |

|---|---|---|

| Solution in the story | "As a user I want a dropdown filter" | Remove the UI decision — "As a user I want to filter by date range" |

| Vague "so that" | "so that it's easier to use" | Make it specific — "so that I can prioritise outreach without opening each record manually" |

| Too big | Story covers 5 distinct user flows | Split into separate stories per flow |

| No acceptance criteria | Story has description only | Add at least 3 GWT criteria before engineering starts |

| ACs that test the solution, not the behaviour | "Given the dropdown is open, When I select an option" | Test the outcome — "Given I have applied a date filter, When I view my results, Then only clients last contacted in that date range appear" |

| Missing empty state | No AC for what happens with 0 results | Add it — empty states are part of the feature |

| Missing error state | No AC for network failure or invalid input | Add error handling ACs explicitly |

---

Example: Full Story Set for a Feature

Feature brief: "Allow users to export their invoice history as a PDF or CSV"

---

Story 1: Export invoice list as CSV

> As a finance admin,

> I want to export my invoice history as a CSV file,

> so that I can import it into our accounting software without manual data entry.

AC1: Successful export

Given I am on the Invoices page with at least one invoice
When I click "Export" and select "CSV"
Then a CSV file is downloaded containing all visible invoices with columns: Invoice ID, Date, Amount, Status, Customer Name

AC2: Empty state

Given I am on the Invoices page with no invoices
When I click "Export"
Then the export button is disabled and a tooltip reads "No invoices to export"

AC3: Filtered export

Given I have applied a date filter showing invoices from Jan 2026 only
When I click "Export" and select "CSV"
Then the export contains only invoices from Jan 2026 — not all invoices

Edge cases:

• [ ] Export with >10,000 invoices — must complete in <30s or show a progress indicator
• [ ] Export triggered on mobile — downloads to device's default download location

Out of scope: PDF export (Story 2), scheduled exports (future epic)

---

Story 2: Export invoice list as PDF

> As a finance admin,

> I want to export my invoice history as a formatted PDF,

> so that I can share a professional summary with our accountant.

[... ACs follow same pattern ...]

---

Scoring Rubric (0–40)

Score any output of this skill before handing it over; 32+ is ship-quality.

| Dimension | 0 | 5 | 10 |

|---|---|---|---|

| User voice & value | Stories written from the system's or developer's perspective; "so that" is missing or circular ("so that it's easier") | Personas are specific but some "so that" clauses describe the feature rather than the outcome the user gets | Every story names a specific user type and a "so that" stating the concrete outcome they achieve — a stakeholder could read it and know why it's worth building |

| AC testability & granularity | ACs missing, or prose descriptions with no pass/fail condition | GWT format used, but criteria bundle multiple behaviours or test the UI solution instead of the observable outcome | One GWT per observable behaviour, each with an unambiguous pass/fail condition, testing outcomes not implementation |

| Unhappy-path coverage | Happy path only — no empty, error, or permission states anywhere | Some edge cases listed, but key failure modes (empty state, mid-flow failure, permission boundaries) are missing or vague | Empty states, error states, permission boundaries, and known technical constraints all appear as explicit ACs or edge cases with defined behaviour |

| Scope discipline & sizing | Stories are epic-sized, interdependent, with no out-of-scope section | Out of scope is present but generic; some stories too large to estimate or ship independently in one sprint | Every story is sprint-sized and independently shippable, splits are recorded with their reason, and Out of Scope names where the next story begins |

Quality Checks

• [ ] Every story has a specific user type — not "a user" or "the system"
• [ ] The "so that" explains business value — not just feature description
• [ ] Each AC tests one observable outcome — not a bundle of behaviours
• [ ] Empty states, error states, and edge cases are explicitly handled
• [ ] Out of scope is documented — not assumed
• [ ] Stories are independent — they can be shipped individually without depending on unreleased work (except where explicitly noted)

Anti-Patterns

• [ ] Do not write user stories from a technical perspective — every story must be from the user's point of view and state their goal
• [ ] Do not write acceptance criteria that are untestable — every criterion must have a clear pass/fail condition
• [ ] Do not create stories that are too large to complete in a single sprint — break epics into estimable, independently deliverable stories
• [ ] Do not omit edge cases — unhappy paths and error states are required, not optional
• [ ] Do not skip the Definition of Done — without it, "done" means different things to different people

Example Trigger Phrases

• "Write user stories for [feature] from this brief"
• "Break this PRD section into user stories with acceptance criteria"
• "Convert these feature requirements into Jira tickets"
• "Write the user stories and ACs for [feature name]"
• "Decompose this epic into individual stories ready for sprint planning"