Software Requirements: User Stories and Acceptance Criteria

By Grocito16 October 2026

Good software requirements say who needs something, what they need, why it matters and how everyone will know it works. Write each need as a user story ("as a role, I want a goal, so that a benefit"), add acceptance criteria that a tester can check as pass or fail, list edge cases and error states, and review it all with developers before building starts.

Key takeaways

Unclear requirements cause rework because each person quietly fills the gaps with their own assumptions.
A user story captures who, what and why. Acceptance criteria capture the exact conditions that make it done.
Write non-functional needs such as speed, security, accessibility and audit trails as testable statements, not adjectives.
Describe the problem and the outcome, and leave the solution open unless a constraint truly demands one.
Treat requirements as a living backlog with a clear change process, not a document signed once and forgotten.

Why do unclear requirements cause rework?

Most expensive software surprises start as a sentence that meant two different things. A business owner writes "customers can download invoices". The developer builds a button that produces a file. The finance team wanted a monthly statement, a company logo, a tax breakdown and a copy emailed automatically.

The later a misunderstanding is found, the more it costs. Clear requirements move that discovery to the cheapest moment, a conversation before any code exists, and they make estimates more honest (see our guide to reading and comparing software development estimates).

What types of requirements should you capture?

It helps to sort needs into four groups so nothing is forgotten.

Business requirements

Why the project exists. Examples: reduce time spent on manual order entry, let the sales team see leads in one place, or open a new sales channel.

Functional requirements

What the system does: create an account, approve a leave request, calculate a delivery charge, send a reminder.

Non-functional requirements

How well the system does it: how quickly pages respond, who may see what, how accessible the screens are, what must be logged for audit, how data is backed up.

Constraints

Fixed boundaries: the budget and deadline, a mandatory payment provider, a hosting region, a legacy system you must connect to, or a regulation your sector must follow. Requirements vary by country and sector, so ask a qualified professional about legal obligations.

How do you write a good user story?

The common pattern is: as a [role], I want [goal], so that [benefit]. A real example reads "As a warehouse supervisor, I want to see orders waiting to be packed, so that I can plan the day's shifts."

Each part does work:

Role: a real person with a real context, not "the user".
Goal: the action or capability, described in the user's language.
Benefit: the reason. This is the part teams skip, and it is the part that lets a developer suggest a better way to achieve the same result.

Keep stories small enough to build and test in a short cycle; if one contains "and" three times, split it.

How do you write acceptance criteria that can be tested?

Acceptance criteria are the conditions that must be true for the story to be accepted. The best ones are statements a tester can mark pass or fail without asking anyone what you meant.

A useful habit is the given, when, then idea, written in words:

Given a customer with an unpaid invoice,
when they open the billing page,
then they see the invoice with its due date and a pay button.

Good criteria describe observable behaviour, include the unhappy paths, and avoid hidden choices. Compare these two:

Weak: "The search should work well."
Testable: "Searching for part of a product name returns matching products. Searching for a term with no matches shows a clear 'no results' message and a link to browse categories. Results appear in the same order every time for the same search."

Which edge cases and error states should you cover?

Happy paths are easy to describe. The effort goes into what happens when things go wrong. For each story, ask:

What if the information is missing, too long, in the wrong format or duplicated?
What if the user lacks permission, or their session expires halfway?
What if the network drops or a connected service is down?
What if two people edit the same record at once?
What message does the user see, and what can they do next?

Writing these down early also shows testers exactly where to look. Our guide to software testing and QA for business applications explains how those conditions turn into test cases.

How do you write non-functional requirements as testable statements?

Words like "fast", "secure" and "user-friendly" cannot be tested. Replace them with a condition and a way to check it.

Performance: "The order list opens within an agreed time on a normal office connection with the expected amount of data." Agree the time with your team and the way you will measure it.
Security: "Only users with the manager role can approve refunds. Every approval is logged with who, what and when."
Accessibility: "All forms can be completed using only a keyboard, and every input has a visible label."
Audit and compliance: "Changes to price records are stored with the previous value, the new value, the user and the time."

How should you prioritise requirements?

Not everything is equally important, and pretending otherwise makes every date unrealistic. A simple MoSCoW sort works well:

Must have: the product fails its purpose without it.
Should have: important, but there is a workaround for a while.
Could have: nice to have if time allows.
Won't have this time: agreed and written down, so it is not a surprise later.

If the first release must contain everything, you do not yet have priorities. For first releases, see our guide to building the right first version.

Why add wireframes and examples to the text?

Words are ambiguous; pictures and sample data are not. A rough wireframe shows which fields a screen holds, and a real example shows what a report or customer record should contain. Put each example next to the criterion it clarifies.

What are definition of ready and definition of done?

These two checklists keep quality consistent.

Definition of ready

A story is ready to build when it has a clear role, goal and benefit, testable acceptance criteria, any design or example it needs, and a size the team can finish in one cycle.

Definition of done

A story is done when the code is reviewed, the acceptance criteria pass, relevant tests are written, error states are handled, documentation is updated and the product owner has seen it working.

A short worked example

Imagine a small training company that wants a leave request feature for its staff. The first draft says "staff can request leave". After a review with a developer and a tester, it becomes:

As an employee, I want to request leave for a date range, so that my manager can approve it before I plan travel.
Given I select an end date before the start date, when I submit, then I see a message explaining the problem and nothing is saved.
Given my manager approves or rejects the request, then I receive an email and the status is updated on my dashboard.

How do you review requirements and control changes?

Before building, run a short review with a developer, a tester and someone from the business. Ask each to read the story and describe it back in their own words. Differences reveal gaps immediately.

Change will happen, so plan for it. A simple change control habit is enough:

Record the change request and the reason.
Describe the effect on scope, time and cost.
Let the decision-maker accept, defer or decline it.
Update the backlog so it always reflects the current plan.

Treat the backlog as living: review it regularly and remove stale items. How you plan the work also matters; see our comparison of agile and waterfall delivery.

What mistakes should you avoid?

Writing the solution instead of the need, such as "add a dropdown" when the need is "choose a delivery slot".
Using vague words like fast, easy, modern or user-friendly without a test.

If you are starting from scratch, our guide on how to write a software project brief is a good first document.

FAQ

What is the difference between a user story and acceptance criteria?

A user story describes who wants something, what they want and why, in one short sentence. Acceptance criteria are the specific, testable conditions that must be true before the story counts as complete. The story explains the purpose and the criteria define the finish line.

How detailed should software requirements be?

Detailed enough that a developer and a tester would build and check the same thing, but not so detailed that you specify the solution. Keep near-term stories precise and leave distant ones rough, then refine them as they approach development.

Who should write the requirements?

The people who understand the business need should lead, usually a product owner or business analyst, with input from users. Developers and testers should review them, because they spot gaps and technical risks that business stakeholders cannot see.

What is a good example of a non-functional requirement?

"Only managers can approve refunds, and every approval is logged with the user and time" is a good example. It names a rule that can be tested and an outcome that can be checked, unlike a vague phrase such as "the system must be secure".

Next steps

Pick one feature that is about to be built and rewrite it as a user story with five or six acceptance criteria, including two error cases. Ask a developer and a tester to read it and explain it back. If you would like help turning a rough idea into clear, buildable requirements, contact us and we can work through it with you.