Acceptance Criteria in Jira: A 7-Step Writing Guide 2026
Unsure what “done” means in Jira? Write clear, testable acceptance criteria with this 7-step guide. Read now to reduce review cycles.
A Jira story can look polished and still leave developers guessing about what “done” means. If acceptance criteria are vague, testers may check different outcomes, and a simple feature can trigger long review cycles.
That uncertainty gets expensive: a button might save the wrong information, a permission rule may go untested, or a team may discover an edge case only after release. Adding more words does not automatically make criteria clearer.
But here's the truth: useful acceptance criteria describe observable outcomes, not implementation guesses. In this seven-step guide, you’ll learn how to write, organize, and review criteria in Jira so your team can agree on success before work begins. A running example will show how to turn a broad request into specific checks that developers and testers can use.
How to Write Acceptance Criteria in Jira: 7 Steps
Acceptance criteria are specific, testable conditions a Jira story must satisfy to be considered complete. Use the seven steps below to make each condition clear to the people building and checking the work.
-

1. Start with the user story and its goal
Read the story first, then identify who needs what and why. Criteria should verify the requested outcome, rather than introduce unrelated work.
For example, “As a customer, I want to reset my password so I can regain access” points to account recovery. It does not automatically require a redesigned sign-in page.
-
2. Agree on the scope
Decide what the story includes and what it leaves out. Scope boundaries help prevent criteria from quietly expanding during development.
For a password-reset story, you might include requesting a reset link and setting a new password. Changing account email addresses could belong in another story.
-
3. Identify observable outcomes
Describe what a person can see or what the system does after an action. Avoid instructions about code, architecture, or internal implementation unless they are genuine requirements.
“The customer sees a confirmation after requesting a reset link” is observable. “The service calls the reset module” describes implementation, not an outcome the customer needs to verify.
-
4. Include important conditions and edge cases
Consider the usual path alongside likely failures, permissions, and limits. You do not need to cover every imaginable exception, but meaningful risks should not be left implicit.
For password resets, consider an unknown email address, an expired link, and a successful password change. These cases make the expected behavior easier to discuss before coding begins.
-
5. Write each criterion so it can be tested
Use precise language and avoid words such as “fast,” “easy,” or “intuitive” unless you define how to assess them. A tester should be able to decide whether each condition passes.
Instead of “the page loads quickly,” specify a measurable limit if performance is part of the requirement. If it is not, leave it out rather than adding a subjective promise.
-
6. Add the criteria to the Jira story
Place the criteria where your team expects to find them, such as the story description or a configured custom field. Keep them attached to the work they define.
Use short bullets for independent checks, or a consistent Given/When/Then format when the team needs a clear setup, action, and result. Jira configurations differ, so follow your team’s conventions.
-
7. Review with the people doing and checking the work
Ask a developer and tester to read the criteria before the story is treated as ready. They can spot missing states, ambiguous terms, and assumptions that need agreement.
For example, “reset link expires” invites a useful question: after how long? Agree on the expected duration, then update the criterion before implementation begins.
What Good Jira Acceptance Criteria Include
Strong criteria connect a story’s goal to outcomes someone can verify. They are specific enough to guide implementation and testing, while leaving room for the team to choose a sensible technical approach.
Here's why: criteria serve as a shared agreement. A product manager can confirm the intended behavior, a developer can understand the boundary, and a tester can check the result without guessing.
- Clear conditions: State the situation or requirement in plain language.
- Observable results: Describe what changes or appears after an action.
- Relevant edge cases: Include likely errors, restrictions, and alternate paths.
- Testable wording: Avoid subjective terms that different people could interpret differently.
- Story-level scope: Keep each condition connected to the outcome the story promises.
For example, “An account holder can request a reset link using a registered email address” is more useful than “Password reset works.” The first condition names an actor, action, and constraint that a tester can check.
When to Use Given/When/Then
Given/When/Then is a useful format when a criterion needs a setup, an action, and an expected result. It can make complex behavior easier to follow, especially when several people need to agree on the same scenario.
Given describes the starting state. When describes the action. Then states the expected outcome.
- Given a customer has an active account
- When they request a password reset using their registered email
- Then the system confirms that a reset link has been sent
The best part? You do not have to force every criterion into this structure. A short, direct bullet may be easier to understand for a simple requirement, such as “The reset link expires after 30 minutes.”
Use the format when the scenario benefits from explicit context. Avoid repeating the same setup across many criteria if it makes the story harder to scan.
Where to Put Criteria in Jira
Jira teams commonly keep acceptance criteria in a story description or a dedicated custom field. Either can work; consistency matters more than choosing one universal location.
Let me explain: criteria should be easy to find during refinement, development, and testing. If some stories keep them in descriptions while others use comments, people may miss important expectations.
A dedicated field can help teams filter, report on, or require criteria during workflow transitions, depending on their Jira configuration. A description section can be simpler for teams that prefer fewer fields and a flexible story template.
Pick a location, show it clearly in your story format, and agree how changes will be discussed. If someone updates a criterion after work starts, make sure the affected teammates know what changed and why.
How to Review Criteria Before Development
A short review can reveal confusion before it becomes rework. Bring the product owner, developer, and tester together when possible, then read each criterion as a separate claim about the expected behavior.
Try asking: “Could two people test this and reach the same conclusion?” If the answer is no, clarify the wording or define the missing condition.
For instance, “show an error for an invalid email” leaves open what counts as invalid and where the error appears. A more useful criterion might specify that an unregistered email produces a neutral message on the reset form.
You might be wondering: should criteria include every technical detail? Usually, include technical constraints only when they affect a required outcome, such as supported browsers, response limits, or access permissions.
Acceptance Criteria Solution: ONES.com
ONES.com brings project management and knowledge management together in one platform powered by ONES Assistant. ONES Project is the project management product and a Jira alternative; ONES Wiki is the knowledge management product and a Confluence alternative. They are sold separately.

For teams refining stories and managing delivery, ONES Project offers Jira-compatible workflows alongside configurable ways to represent work. That can help teams keep acceptance criteria close to planning, implementation, and reporting.
Core Capabilities
- Scattered story details → Custom workflows and fields → Place acceptance criteria in a consistent part of the work item, so teammates know where to review expectations.
- Unclear progress across stories → Built-in reporting → Give teams a view of project progress without relying on manually assembled status updates.
- Different delivery methods → Jira-compatible workflows → Support familiar workflow patterns while teams configure processes to match how work moves through review and completion.
- Hard-to-manage sprint work → Sprint management → Organize stories and criteria as part of sprint planning and delivery, helping teams connect planned work with its completion conditions.
- Repeated process steps → Automation → Reduce routine workflow administration when a team’s rules can be expressed as automated actions.
- Feature gaps requiring add-ons → Broad native capabilities → Use built-in project functions and reduce dependence on plugins where those native capabilities meet the team’s needs.
- Restricted hosting requirements → On-premise, private cloud, and air-gapped deployment options → Choose a deployment approach that fits organizational security and infrastructure constraints.
- Concern about deployment trade-offs → Feature parity between cloud and self-hosted versions → Evaluate deployment choice without assuming that self-hosting means giving up feature coverage.
Application Scenarios
A product team standardizing story readiness: A team can configure a workflow that keeps story review and acceptance criteria visible before development begins. Custom fields can help make required details consistent across stories.
An organization with restricted network needs: Teams that cannot use a public cloud deployment can consider ONES Project on-premise, in a private cloud, or in an air-gapped environment. The deployment choice can be aligned with internal operating requirements.
A team consolidating project practices: A team comparing Jira alternatives can assess familiar workflows, sprint management, reporting, custom fields, and automation in one project management environment. ONES.com offers a free plan for up to 30 seats, making an initial evaluation possible.
Common Challenges With Jira Acceptance Criteria
- Problem: Criteria describe solutions rather than outcomes. A line such as “add a new API method” may miss the user need. Solution: State the behavior the story must deliver, then record technical choices separately when they matter.
- Problem: The wording is too broad to test. “The experience should be smooth” leaves different interpretations. Solution: Name the action, state, or measurable threshold that demonstrates success.
- Problem: Edge cases surface late. A team may overlook expired links or access restrictions. Solution: During review, identify likely failure paths and add only those that affect the story’s intended behavior.
- Problem: Criteria change without shared understanding. Developers and testers may continue working from different expectations. Solution: Keep the criteria with the Jira story, discuss material changes, and confirm the updated outcome with the affected teammates.
FAQs About Acceptance Criteria in Jira
Are acceptance criteria the same as a definition of done?
No. Acceptance criteria describe the specific outcomes a story needs to meet. A definition of done is usually a shared team standard applied across many stories, such as completing code review or passing agreed checks. A password-reset story might require a valid reset link as a criterion, while the team’s definition of done may require testing and review for every completed story.
How many acceptance criteria should a Jira story have?
There is no fixed number that fits every story. Add enough criteria to cover the meaningful outcomes and likely cases, while keeping each story focused. A small change might need two clear conditions; a flow involving permissions, errors, and several user states may need more. If the list becomes unwieldy, consider whether the work should be split into smaller stories.
Can acceptance criteria be added after development starts?
They can be clarified or changed, but the team should discuss the impact first. A new condition may affect scope, estimates, implementation, or testing. Update the Jira story so everyone can see the agreed expectation, then tell the teammates whose work may change. For example, adding a new account-lockout rule after coding begins could require additional development and test coverage.
Should I use a Jira custom field for acceptance criteria?
A custom field can make criteria easier to locate and can support workflow rules or reporting, depending on your Jira setup. A section in the story description may be more convenient if your team wants a simple template. Choose the approach your team will use consistently, then make the location obvious during refinement and review.
Do acceptance criteria need to use Given/When/Then?
No. Given/When/Then can clarify scenarios that need a defined starting state, action, and result. For a straightforward condition, a concise bullet may be easier to read. Use the format that makes the expected behavior clear to the people building and testing the story, rather than adopting it as a requirement for every Jira issue.
Conclusion
Clear criteria help your Jira team agree on what a story must accomplish before development and testing begin. Start with the user’s goal, set boundaries, describe observable outcomes, consider important edge cases, and review each condition for testability.
When criteria stay vague, teams risk mismatched expectations and avoidable rework. A consistent story format and a brief cross-functional review give everyone a clearer path to completion. Apply these seven steps to your next story, then adjust the team’s conventions as you learn what works.