Acceptance Criteria Writing | Define Done Clearly

Write acceptance criteria that define exactly what done means. GitScrum tasks with clear, testable conditions get completed right the first time with less rework.

7 min read

Vague requirements lead to misunderstandings, rework, and frustration. Clear acceptance criteria define exactly what needs to be true for a task to be complete. GitScrum tasks with well-defined acceptance criteria get completed right the first time.

Why Acceptance Criteria Matter

Without Clear Criteria	With Clear Criteria
"I thought you meant..."	Shared understanding
Rework after review	Right the first time
Scope creep	Clear boundaries
QA doesn't know what to test	Testable conditions
Endless back-and-forth	Quick verification

Acceptance Criteria Formats

Given-When-Then Format

GIVEN-WHEN-THEN (Gherkin Syntax)
════════════════════════════════

FORMAT:
GIVEN [precondition/context]
WHEN [action/trigger]
THEN [expected outcome]

EXAMPLE: User Login
─────────────────────────────────────
GIVEN a registered user on the login page
WHEN they enter valid credentials
THEN they are redirected to the dashboard
AND they see a welcome message with their name

GIVEN a user on the login page
WHEN they enter an invalid password
THEN they see an error message "Invalid credentials"
AND the password field is cleared
AND the login attempt is logged

GIVEN a user who is already logged in
WHEN they navigate to the login page
THEN they are redirected to the dashboard
─────────────────────────────────────

Checklist Format

CHECKLIST FORMAT
════════════════

EXAMPLE: Search Feature

Acceptance Criteria:
- [ ] User can enter search terms in the search box
- [ ] Search executes when user presses Enter or clicks Search
- [ ] Results display within 2 seconds
- [ ] Results show title, excerpt, and date for each match
- [ ] "No results found" message displays when no matches
- [ ] Minimum 2 characters required to search
- [ ] Search terms are highlighted in results
- [ ] User can clear search and return to default view
- [ ] Search works on mobile (responsive)
- [ ] Search history is not saved (privacy)

Rule-Based Format

RULE-BASED FORMAT
═════════════════

EXAMPLE: Password Requirements

Rules:
1. Password must be 8-64 characters
2. Must contain at least one uppercase letter
3. Must contain at least one lowercase letter
4. Must contain at least one number
5. Must contain at least one special character (!@#$%^&*)
6. Cannot contain spaces
7. Cannot match any of the last 5 passwords
8. Cannot contain the username
9. Strength meter updates in real-time
10. Error messages explain which rule fails

Writing Quality Criteria

Good vs Bad Examples

ACCEPTANCE CRITERIA QUALITY
═══════════════════════════

BAD (vague):
✗ "User can search"
✗ "Make it fast"
✗ "Handle errors properly"
✗ "Should work on mobile"
✗ "Validate input"

GOOD (specific and testable):
✓ "User can search by entering text and pressing Enter"
✓ "Search results display within 2 seconds for up to 10,000 records"
✓ "Invalid email shows error: 'Please enter a valid email address'"
✓ "Form is fully functional at 320px viewport width"
✓ "Email field accepts only valid email format (user@domain.ext)"

Coverage Areas

WHAT TO COVER IN ACCEPTANCE CRITERIA
════════════════════════════════════

HAPPY PATH:
├── Normal successful flow
├── Expected user behavior
└── Main use case

EDGE CASES:
├── Empty states
├── Boundary values
├── Unusual but valid inputs
└── Concurrent actions

ERROR SCENARIOS:
├── Invalid input
├── Network failures
├── Permission denied
├── Timeout handling
└── System errors

NON-FUNCTIONAL:
├── Performance requirements
├── Accessibility (WCAG level)
├── Browser/device support
├── Security requirements
└── Localization needs

Template for User Stories

USER STORY WITH ACCEPTANCE CRITERIA
═══════════════════════════════════

STORY:
As a [type of user]
I want to [action/goal]
So that [benefit/value]

ACCEPTANCE CRITERIA:

Happy Path:
- [ ] [Main success scenario 1]
- [ ] [Main success scenario 2]

Edge Cases:
- [ ] [Edge case 1]
- [ ] [Edge case 2]

Error Handling:
- [ ] [Error scenario 1]
- [ ] [Error scenario 2]

Non-Functional:
- [ ] [Performance requirement]
- [ ] [Accessibility requirement]

Out of Scope:
- [Explicitly what's NOT included]
- [To prevent scope creep]

Real-World Examples

E-commerce Cart Example

TASK: Add to Cart Functionality

ACCEPTANCE CRITERIA:

Adding Items:
- [ ] User can add product to cart from product page
- [ ] User can specify quantity before adding (1-99)
- [ ] Cart icon shows updated count immediately
- [ ] "Added to cart" confirmation shows for 3 seconds
- [ ] Product with selected options (size, color) is added

Cart Behavior:
- [ ] Adding same product increases quantity (doesn't duplicate)
- [ ] Cart persists across sessions (logged in users)
- [ ] Cart persists for 30 days (guest users via cookie)

Edge Cases:
- [ ] Adding more than available inventory shows stock message
- [ ] Out of stock products show "Notify Me" instead of "Add"
- [ ] Maximum cart size is 50 unique items

Errors:
- [ ] Network error shows "Unable to add. Please try again."
- [ ] Product no longer available shows appropriate message

Performance:
- [ ] Add to cart completes in <500ms
- [ ] Cart updates without page reload

OUT OF SCOPE:
- Wishlist functionality (separate task)
- Guest checkout (handled in checkout task)

API Endpoint Example

TASK: Create User Registration Endpoint

ACCEPTANCE CRITERIA:

Request:
- [ ] POST /api/v1/users/register
- [ ] Accepts JSON body: email, password, name
- [ ] Content-Type: application/json

Validation:
- [ ] Email: valid format, unique in system
- [ ] Password: 8+ chars, uppercase, lowercase, number
- [ ] Name: 2-100 characters, alphanumeric + spaces

Success (201):
- [ ] Returns user ID, email, name
- [ ] Does NOT return password
- [ ] Creates user in database with hashed password
- [ ] Sends verification email
- [ ] Logs registration event

Errors:
- [ ] 400: Invalid input (with field-level errors)
- [ ] 409: Email already exists
- [ ] 422: Validation failed
- [ ] 429: Rate limited (5 attempts per IP per minute)

Security:
- [ ] Password never logged
- [ ] Uses bcrypt with cost factor 12
- [ ] HTTPS only
- [ ] CORS configured for allowed origins

Best Practices

For Writing Criteria

Be specific — Numbers, exact messages, precise behavior

Be testable — Can verify pass/fail objectively

Focus on what, not how — Requirements, not implementation

Include negative cases — What should NOT happen

Define "done" — No ambiguity about completion

Collaborative Refinement

REFINEMENT PROCESS
══════════════════

1. DRAFT: Product owner writes initial criteria
2. REVIEW: Team reviews in refinement meeting
3. CLARIFY: Developers ask clarifying questions
4. EXPAND: Add edge cases and error scenarios
5. CONFIRM: QA validates criteria are testable
6. FINALIZE: All agree criteria are complete

QUESTIONS TO ASK:
├── "What happens if...?"
├── "Is there a maximum/minimum?"
├── "How do we handle errors?"
├── "What's explicitly out of scope?"
└── "How will QA verify this?"

Anti-Patterns

ACCEPTANCE CRITERIA MISTAKES:
✗ Too vague ("should work well")
✗ Too detailed (implementation specifics)
✗ Missing error cases
✗ No performance criteria
✗ Not reviewed by developers
✗ Not reviewed by QA
✗ Changed mid-sprint without discussion
✗ No out-of-scope section