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

Create User Story

User stories capture requirements from the end-user perspective. Each story follows the format: "As a [who], I want [what], so that [why]." This structure ensures every feature has clear purpose and measurable value.

Opening the Modal

Access the creation modal through multiple paths:

• Project header: Click "New" button in user stories section
• Keyboard shortcut: Cmd/Ctrl + Shift + U from anywhere in project
• Empty state: Click "Create your first user story" link
• Quick create: Use global quick create menu and select "User Story"

The modal opens with your current project pre-selected. If you opened from the global menu, select workspace and project first.

Creation Modes

Traditional Mode

Write user stories in the standard format:

Template structure:

As a [type of user],
I want [some goal],
So that [some reason].

Example:

As a project manager,
I want to see sprint burndown charts,
So that I can track team velocity.

The traditional format ensures:

• Clear identification of the user persona
• Specific, actionable goal statement
• Business value justification

Writing effective stories:

1. Be specific about the user. "As a user" is too vague. Use "As a billing administrator" or "As a first-time visitor"

1. Focus on one goal. If you write "and" in the want clause, consider splitting into multiple stories

1. State measurable value. "So that I can save time" is weak. "So that I can process 50% more invoices" is actionable

AI Mode

Describe what you need in natural language. The AI generates a properly formatted user story:

Input:

Need a way for managers to approve time entries before they go to billing

Generated story:

As a team manager,
I want to review and approve time entries before export,
So that billing accuracy improves and disputes decrease.

AI mode excels when:

• Converting stakeholder requests into user story format
• Transforming bug reports into improvement stories
• Breaking down vague requirements into specific needs

Modal Fields

Title (Required)

In Traditional mode, this is your full user story text. In AI mode, this is your natural language description.

Character limit: 500 characters Best practice: Keep titles scannable. The first line should summarize the story.

Acceptance Criteria

Define what "done" means for this story. Use testable conditions:

Weak criteria:

- Should work properly
- Must be fast
- Needs to look good

Strong criteria:

- Time entries display in chronological order
- Manager can approve/reject individual entries
- Rejected entries return to submitter with required comment
- Approved entries marked with timestamp and approver name
- Page loads within 2 seconds for up to 500 entries

Format options:

Given/When/Then:

Given I am a logged-in manager
When I view pending time entries
Then I see entries grouped by team member

Checklist style:

- [ ] Filter by date range works
- [ ] Bulk approve selected entries works
- [ ] Export approved entries to CSV works

Additional Information

Context that helps during implementation:

• Links to design mockups
• Technical constraints
• Related documentation
• Stakeholder contacts
• Edge cases to consider

This field supports full Markdown formatting including links, code blocks, and images.

Priority

Set urgency level from your project's priority list:

Priority affects:

• Default sorting in backlog views
• Sprint planning suggestions
• Team workload calculations

Epic

Link the story to a parent epic for organization:

No Epic selected: Story appears in backlog without grouping Epic selected: Story groups under epic in roadmap and planning views

Create Epic inline: Click "Create new epic" to add an epic without leaving the modal. Enter title and save—the new epic is immediately selectable.

This is valuable when:

• A story reveals need for a new initiative
• Stakeholder requests a feature outside existing epics
• You're breaking down a large requirement into epic + stories

Form Validation

The create button enables when:

1. Project selected: Required for all stories
2. Title provided: Minimum 3 characters
3. Mode-appropriate content: Either traditional format or AI description

Validation errors appear inline:

• Empty title: "Title is required"
• Title too short: "Minimum 3 characters"
• No project: "Select a project first"

After Creation

Success State

The modal confirms creation with options:

Go to User Stories: Navigate to the project's user story board Create Another: Clear form, stay in modal for batch creation

What Happens

1. Story created with "Open" status
2. Appears in backlog ready for sprint planning
3. Linked to epic if selected
4. Team notified via project activity feed
5. Real-time sync across all team members' views

Keyboard Shortcuts

Best Practices

Write Independently

Each story should be completable without dependencies:

Dependent (avoid):

As a user, I want to see the dashboard that was created in US-123

Independent (preferred):

As a user, I want to see key metrics on my dashboard

Size Appropriately

Stories should complete within one sprint. If larger:

• Break into multiple stories
• Use epic to group related stories
• Consider "As a user, I want [part 1]" pattern

Include Acceptance Criteria

Every story needs testable conditions. This is not optional—it's how your team knows when work is complete.

Time investment: 5 minutes writing criteria saves 2 hours of clarification questions later.

Connect to Epics

Orphan stories create planning chaos. Even "miscellaneous improvements" deserve an epic for grouping.

Common Patterns

Feature Story

As a [user type],
I want [capability],
So that [business value].

Bug-to-Story Conversion

As a [affected user],
I want [broken thing] fixed,
So that [impact when fixed].

Technical Story

As a developer,
I want [technical improvement],
So that [maintenance/performance benefit].

Research Story

As a product manager,
I want to understand [unknown],
So that [future decisions].

Troubleshooting

Modal won't open:

• Check project permissions (need createuserstories)
• Ensure project is selected in navigation
• Try page refresh

AI mode not generating:

• Provide more detail in description
• Include context about user type and goal
• Check network connection

Can't select epic:

• Epics load after project selection
• Create new epic if none exist
• Check epic isn't archived

Priority dropdown empty:

• Priorities come from project settings
• Admin can add priorities in Project Settings → Priorities