---
name: user-story-writing
description: "Stories sliced so each one ships something a user would notice, with testable acceptance criteria and a list of ambiguities to settle before anyone builds. Use when a team lead needs a feature description sliced into thin, shippable stories with testable criteria and has not yet found the ambiguities. Do not use for mapping a whole epic across a user journey or filling a single Jira template. Related topics: Product, Planning, Communication."
---

# User Story Writing

Stories sliced so each one ships something a user would notice, with testable acceptance criteria and a list of ambiguities to settle before anyone builds.

## When to use

Use this skill when a team lead needs a feature description sliced into thin, shippable stories with testable criteria and has not yet found the ambiguities. Do not use it for mapping a whole epic across a user journey or filling a single Jira template.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Identify the smallest slice that a user would notice and make it the first story.
3. Slice the rest by user-visible value, done when no story is named after a technical layer.
4. Write testable acceptance criteria for each: happy path, edge cases, error states, and permissions.
5. Check each story against the current behaviour and technical context for conflicts.
6. List every ambiguity that could lead two developers to build different things, with a question for each.

## Inputs

- **The feature** (longer free text)
- **Who uses it and in what situation** (longer free text)
- **What happens today** (longer free text)
- **Technical context the team needs** (longer free text)

## Output

An ordered list of stories each with acceptance criteria in four groups, then a list of ambiguities with the question that resolves each.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Writing User Stories

Turn the feature below into user stories.

- The feature: {{The feature}}
- Who uses it and in what situation: {{Who uses it and in what situation}}
- What happens today: {{What happens today}}
- Technical context the team needs: {{Technical context the team needs}}

Slice by user-visible value, not by technical layer. No story called build the backend.

Give each story acceptance criteria in testable form: the happy path, the edge cases, the error states, and the permission conditions.

Then flag anything in the description ambiguous enough that two developers would build it differently, because that is worth catching now rather than at review.

## Pitfalls

- Naming stories after layers like build the API, which delivers nothing a user can see.
- Writing criteria such as works correctly, which cannot be tested.
- Skipping permission conditions, which then surface late as security bugs.
