PoliteTools

Product & QA

User Story Generator

Fill in the role, the want and the reason, then add acceptance criteria in Given-When-Then form. The output is clean Markdown you can paste straight into a ticket, structured the way a developer and a tester both need it.

nothing you type is sent anywhere

Loading tool…

How to use User Story Generator

  1. Write the story: as a role, I want something, so that some outcome.

  2. Add a scenario for each behaviour worth verifying, in Given-When-Then form.

  3. Add notes for scope boundaries, dependencies or open questions.

  4. Copy the Markdown into your tracker.

Why the format exists at all

The As a / I want / So that structure is not ceremony. It forces three pieces of information that tickets routinely omit: who this is for, what they are trying to do, and why it matters to them. A ticket missing any of the three pushes the guessing onto whoever picks it up.

The role matters because software behaves differently for different people, and a story written for an unspecified user tends to get built for the developer's mental model of an average one. Naming the role — a returning customer, a first-time visitor, an administrator — frequently changes the design.

The want should describe a goal, not an implementation. "I want a dropdown of saved addresses" specifies a solution; "I want to reuse an address I have entered before" describes the need, and leaves room for a better answer than a dropdown.

The clause everybody drops

The "so that" is skipped more than any other part, and it is the one that changes outcomes. It converts a feature request into a problem statement, which is the difference between a team that builds what was asked for and one that solves what was needed.

It also gives you the means to say no well. A story whose stated outcome is already achieved another way can be closed with a reason rather than a judgement, and a story that cannot articulate an outcome at all has just told you something important about itself.

When you cannot write the clause, that is the signal to go and ask. Someone requested this for a reason; if nobody in the room can state it, the requirement is not yet understood well enough to build.

Acceptance criteria that a tester can use

Given-When-Then works because each part has a job. Given fixes the starting state, When names a single specific action, and Then states an observable result. Anything that fails to fit the shape is usually vague in a way that would have caused an argument at review.

The test of a good criterion is whether a tester can tell unambiguously whether it passed. "The page should be fast" fails. "Given a basket of fifty items, when I open checkout, then the total renders within two seconds" passes, and it also surfaces a performance requirement that would otherwise have gone unstated.

Three to seven scenarios is the usual range. If you find yourself writing fifteen, the story is several stories, and splitting it will make estimating, reviewing and testing all easier.

Where stories stop being the right tool

Not everything is a user story, and forcing everything into the format produces some memorably absurd tickets. Infrastructure work, dependency upgrades, refactoring and spikes have no user-facing want, and writing "as a developer I want to upgrade the framework" adds nothing but a costume.

Bugs are not stories either. A defect has a reproduction, an expected result and an actual result, which is a different shape entirely and is served better by a bug report.

The useful rule is to use the format where it earns its keep — work whose value depends on who it is for and why — and to write plainly everywhere else. A team that recognises the difference writes better tickets than one applying the template universally.

Frequently asked questions

Why does the "so that" clause matter so much?

Because it is the difference between a feature request and a problem statement. "As a user I want a CSV export" tells a developer what to build; "so that I can reconcile figures against our accounting system" tells them what problem to solve — and sometimes reveals that a direct integration, or a differently shaped report, serves the person better. Teams that drop the clause end up building exactly what was asked for and not what was needed.

What makes a good acceptance criterion?

It is observable and unambiguous. Given-When-Then works because it forces a starting state, a specific action and a result you can point at. "The page should be fast" fails both tests; "Given a basket of 50 items, when I open checkout, then the total renders within two seconds" passes. If a tester cannot tell whether it passed, it is not a criterion.

How many criteria should a story have?

Enough to define done, and few enough that the story stays deliverable. Three to seven scenarios is typical. If you are writing fifteen, the story is almost certainly several stories wearing a trenchcoat, and splitting it will make estimation, review and testing all easier.

Do acceptance criteria replace test cases?

No, they anchor them. Criteria describe the behaviour that must hold for the story to be accepted; test cases include the edge cases, error paths and negative scenarios a tester adds on top. A good rule is that every criterion becomes at least one test, and a good tester writes several more.

Is anything I type here sent to a server?

No. The story is assembled in your browser and nothing is transmitted or stored. Unreleased product plans are exactly the sort of thing not to paste into a website that uploads.

What next