Acceptance Criteria

Acceptance criteria define the conditions that must be met for a user story to be considered complete. They transform vague requirements into testable specifications, eliminating ambiguity and preventing scope creep.

Purpose

Acceptance criteria serve multiple roles:

For developers: Clear requirements before coding starts For testers: Exact conditions to verify For stakeholders: Transparent definition of deliverables For product owners: Scope boundary enforcement

Without acceptance criteria, "done" becomes subjective. With them, completion is binary—all criteria pass or work continues.

Accessing the Editor

Open acceptance criteria from the user story details:

1. Navigate to any user story
2. Click the Details tab
3. Find Acceptance Criteria section
4. Click the Edit button (pencil icon)

The editor opens in a modal with rich text formatting options.

Editor Features

Formatting Toolbar

The acceptance criteria editor supports:

Rich Text Support

The editor preserves formatting when pasting from:

• Google Docs
• Confluence
• Notion
• Microsoft Word

Paste formatted content directly—structure transfers automatically.

Writing Effective Criteria

The Given-When-Then Format

This structure creates unambiguous, testable conditions:

Given [precondition]
When [action]
Then [expected result]

Example:

Given I am logged in as an administrator
When I click "Delete User" and confirm the dialog
Then the user is removed from the system
And I see a success notification
And the user no longer appears in the user list

Checklist Format

For simpler validations, use checkboxes:

- [ ] Form validates email format
- [ ] Password requires 8+ characters
- [ ] Submit button disabled until form valid
- [ ] Error messages display below invalid fields
- [ ] Success redirects to dashboard

Specification by Example

Show exact expected behavior:

Input: "john@example.com"
Expected: Valid, proceed to next step

Input: "john@"
Expected: Error "Invalid email format"

Input: ""
Expected: Error "Email is required"

Criteria Categories

Functional Criteria

What the feature must do:

Given a user with items in cart
When they click "Checkout"
Then they see the payment form
And cart total displays correctly
And shipping options are calculated

Non-Functional Criteria

How the feature must perform:

Performance:
- Page loads within 2 seconds
- Search returns results within 500ms
- Supports 100 concurrent users

Accessibility:
- All form fields have labels
- Tab navigation works correctly
- Screen reader compatible

Edge Cases

Boundary conditions and error states:

Edge cases handled:
- Empty search returns helpful message
- Network timeout shows retry option
- Session expiry redirects to login
- Invalid data shows specific errors

Security Criteria

Protection requirements:

Security requirements:
- Passwords hashed before storage
- Session expires after 30 min inactivity
- Failed logins limited to 5 attempts
- Sensitive data not logged

Anti-Patterns to Avoid

Too Vague

❌ Bad:

- Should work correctly
- Must be fast
- Needs to handle errors

✅ Good:

- Returns 200 status on valid input
- Responds within 500ms under normal load
- Shows "Network error, please retry" on timeout

Too Technical

❌ Bad (unless team is all developers):

- Uses Redis pub/sub for real-time updates
- Implements optimistic locking with ETag
- Deploys via Kubernetes rolling update

✅ Good:

- Changes appear for all users within 3 seconds
- Simultaneous edits show conflict warning
- Deployment causes zero downtime

Testing the Implementation

❌ Bad:

- Uses React hooks correctly
- Database queries are optimized
- Code follows style guide

✅ Good:

- Component re-renders only when data changes
- List loads within 1 second for 10,000 items
- Consistent with existing UI patterns

Scope Creep

❌ Bad (adds work not in story):

- Also add dark mode support
- Include export to PDF option
- Add keyboard shortcuts

✅ Good (stick to story scope):

- Dashboard displays all widgets
- Widgets load user's saved configuration
- Layout persists across sessions

Integration with Workflow

During Planning

1. Story creation: Draft initial criteria
2. Refinement: Team discusses, adds edge cases
3. Estimation: Criteria inform story point assignment
4. Sprint planning: Criteria verify story is ready

During Development

1. Reference: Developer checks criteria while coding
2. Self-test: Developer verifies each criterion before PR
3. Code review: Reviewer checks criteria coverage

During Testing

1. Test case creation: Each criterion becomes test case
2. Verification: Tester validates all criteria
3. Bug reports: Reference specific failed criteria

During Demo

1. Walkthrough: Show each criterion being met
2. Sign-off: Stakeholder confirms acceptance

Keyboard Shortcuts

In the acceptance criteria editor:

Best Practices

1. Write Criteria Before Development

Criteria written after coding tend to match implementation rather than requirements. Write first, code second.

2. Involve the Team

Developers spot technical gaps. Testers find edge cases. Include both perspectives when writing criteria.

3. Keep Criteria Atomic

Each criterion tests one thing:

❌ Combined:

User can log in with correct credentials and sees dashboard with their data

✅ Atomic:

- Valid credentials grant access
- Invalid credentials show error
- Dashboard displays after login
- Dashboard shows user's data only

4. Use Consistent Language

Establish team conventions:

• "User" vs "Customer" vs "Member"
• "Click" vs "Select" vs "Choose"
• "Display" vs "Show" vs "Render"

5. Include Negative Cases

What should NOT happen matters too:

- Password is never displayed in logs
- Deleted data cannot be recovered
- Expired session cannot access protected routes

6. Version Control Criteria

When requirements change, update criteria and note why:

Updated 2024-01-15: Added 2FA requirement per security audit
Previous: Login requires email + password
Current: Login requires email + password + 2FA code

Common Templates

CRUD Operations

Create:
- Valid input creates record
- Invalid input shows specific errors
- Duplicate prevention works

Read:
- Authorized users see data
- Unauthorized users see error
- Empty state shows helpful message

Update:
- Changes save correctly
- Validation applies to updates
- Concurrent edit handling works

Delete:
- Confirmation required
- Soft delete preserves data
- Hard delete removes completely

Form Validation

Field: Email
- Required (shows error when empty)
- Format validation (user@domain.com)
- Max length: 254 characters
- Unique check (shows error if exists)

Field: Password
- Required
- Minimum 8 characters
- At least one number
- At least one special character
- Strength indicator displays

API Endpoint

Endpoint: GET /api/users/{id}

Success (200):
- Returns user object
- Excludes sensitive fields (password, tokens)
- Response time < 200ms

Not Found (404):
- Returns standard error format
- Message: "User not found"

Unauthorized (401):
- Missing token returns error
- Expired token returns error
- Invalid token returns error

Troubleshooting

Formatting not saving:

• Check browser console for errors
• Try clearing browser cache
• Ensure stable network connection

Editor won't open:

• Verify edituserstories permission
• Check story isn't archived
• Refresh page and retry

Pasted content loses format:

• Try Paste and Match Style (Cmd/Ctrl + Shift + V)
• Use Markdown format for complex content
• Break into smaller paste operations

Changes not visible to team:

• Verify save completed (modal closed)
• Check for sync errors in activity feed
• Team members may need to refresh