write-user-story— agent skill

What this skill does

Produces a complete, ready-to-groom user story following the standard Atlassian/agile format. It applies the INVEST criteria and the 3 Cs framework (Card, Conversation, Confirmation) to ensure each story is well-scoped, valuable, and testable — not just syntactically correct.

Reference: Atlassian — User stories with examples and a template

When to use it

• User asks to "write a user story" or "create a story" for a feature or requirement.
• User wants to refine a rough idea, acceptance note, or bug description into a proper story.
• User needs to validate whether an existing story is well-formed.
• User is decomposing an epic into individual stories.

Key concepts

The standard format (Connextra template)

As a [persona],
I want to [action / capability],
so that [benefit / outcome].

• Persona — who benefits (not "user" generically — use a real role: "logged-in customer", "warehouse operator", "admin").
• Want — the capability or action, not the implementation ("I want to filter results" not "I want a dropdown").
• Benefit — the why; if the benefit is obvious, keep it short but never omit it.

INVEST criteria

A well-formed story is:

3 Cs

• Card — the written story (brief; a reminder, not a spec).
• Conversation — the discussion between team and stakeholders that fills in detail.
• Confirmation — the acceptance criteria that confirm the story is done.

Instructions

1. Identify the persona. Use the most specific role that benefits from this story. Avoid "user" alone.

1. State the want. Describe what the persona wants to do, not how the system implements it. Focus on the outcome, not the feature.

1. State the benefit. Explain why this matters to the persona or the business. If the user did not provide one, infer it from context and flag it for confirmation.

1. Write the story card using the Connextra template.

1. Check INVEST. Flag any criterion the story fails and suggest a fix:

• Too large → split into smaller stories.
• Too vague to estimate → add a constraint or scope note.
• Not independently deliverable → identify the dependency.

1. Write acceptance criteria using Given/When/Then (Gherkin) or a plain bulleted list if Gherkin is too heavyweight:

• Each criterion must be independently verifiable.
• Cover the happy path and at least one edge case.
• Avoid implementation details in criteria.

1. Add a Definition of Done reminder (standard checklist unless the user provides a custom one).

1. Produce the output using the format below.

Output format

## User Story: [short title]

**As a** [persona],  
**I want to** [action],  
**so that** [benefit].

---

### Acceptance Criteria

- [ ] Given [context], when [action], then [outcome].
- [ ] Given [context], when [action], then [outcome].
- [ ] [Edge case or negative path]

### Definition of Done

- [ ] Acceptance criteria all pass.
- [ ] Code reviewed and merged.
- [ ] Unit/integration tests written and passing.
- [ ] Documented (if applicable).
- [ ] Deployed to staging and smoke-tested.

### INVEST check

| Criterion | Status | Note |
| --- | --- | --- |
| Independent | Pass / Fail | ... |
| Negotiable | Pass / Fail | ... |
| Valuable | Pass / Fail | ... |
| Estimable | Pass / Fail | ... |
| Small | Pass / Fail | ... |
| Testable | Pass / Fail | ... |

### Notes

- [Dependencies, assumptions, or open questions]

Examples

Example 1 — Filter a product list

Input: "Write a story for filtering search results by price range."

Expected output:

## User Story: Filter search results by price range

**As a** shopper,  
**I want to** filter product search results by a minimum and maximum price,  
**so that** I only see products I can afford and avoid scrolling through irrelevant results.

### Acceptance Criteria

- [ ] Given I am on a search results page, when I set a minimum price of $10 and a maximum of $50 and apply the filter, then only products priced between $10 and $50 are shown.
- [ ] Given I apply a price filter, when no products match, then a "No results found" message is shown and the filter values are preserved.
- [ ] Given I apply a price filter, when I clear it, then all results are restored.

Example 2 — Vague input requiring a split

Input: "User can manage their account."

Expected output: Story flagged as failing Small (too broad) and Estimable (too vague). Skill proposes a split into: change email, change password, delete account — each as a separate story.

Notes

• A story card should fit on an index card. If the "want" clause needs multiple sentences, the story is likely too large — split it.
• Do not write stories in the passive voice ("It should be possible to…") — keep the persona as the subject.
• Acceptance criteria are not a full test plan; they define the boundaries of done, not every test case.
• If the user does not provide a persona, ask for one before writing — guessing the wrong role produces the wrong story.