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:

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:

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 ...]

Deeper Materials

This skill ships with support files — use them when they are available:

• references/acceptance-criteria-craft.md — Acceptance Criteria That Actually Gate. Apply it while producing the output; it carries the calibration and judgment calls the method summary above compresses.
• templates/story-card.md — a fill-in version of the deliverable with the quality gates inline. Offer it when the user wants to work the document themselves rather than have it generated.

Scoring Rubric (0–40)

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

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"