user-story-acceptance-criteria

name	user-story-acceptance-criteria
description	User story writing patterns with comprehensive acceptance criteria categories and quality standards. Use when creating user stories, defining acceptance criteria, or reviewing story completeness for multi-tenant applications.

User Story Acceptance Criteria Patterns

Comprehensive patterns for writing user stories with well-defined acceptance criteria that ensure clarity, testability, and completeness.

Acceptance Criteria Categories

Core Functionality

Main feature behavior and primary user workflows

**Example: Create Venue Story**

**Core Functionality:**
- User can create a new venue with name, address, capacity, and venue type
- System assigns unique ID and creation timestamp to new venue
- User is redirected to venue details page after successful creation
- New venue appears in venue list for the tenant

Input Validation

Field requirements, data formats, constraints, and business rules

**Input Validation:**
- Venue name is required (1-200 characters)
- Address is required (1-500 characters)
- Capacity must be a positive integer (1-100,000)
- Venue type must be selected from predefined list
- Postal code must match valid format for selected country
- Duplicate venue names within tenant are not allowed

User Experience

Navigation, feedback, error messages, and loading states

**User Experience:**
- Form fields show validation errors immediately on blur
- Submit button is disabled while form is invalid
- Loading spinner appears during venue creation
- Success toast shows "Venue created successfully" message
- Cancel button returns to venue list without saving
- Form remembers partially entered data if user navigates away

Security & Access Control

Authentication, authorization, and data isolation requirements

**Security & Access Control:**
- Only authenticated users can create venues
- User must have 'venue-manager' or 'admin' role
- Created venue is automatically assigned to user's tenant
- User cannot see or access venues from other tenants
- API endpoints validate tenant context in JWT token

Data Integrity

Uniqueness constraints, required data, timestamps, and relationships

**Data Integrity:**
- Venue ID is unique across all tenants
- Created venue must have valid tenant association
- CreatedAt and UpdatedAt timestamps are automatically set
- Venue type must exist and be active
- Address validation ensures complete location data

Error Handling

Error scenarios and user-facing error messages

**Error Handling:**
- Network errors show "Unable to save venue. Please try again."
- Duplicate name error shows "A venue with this name already exists"
- Invalid capacity shows "Capacity must be between 1 and 100,000"
- Server errors show generic "An error occurred. Please contact support."
- Validation errors are shown inline with specific field guidance

User Story Template

Standard Format

**As a** [persona]
**I want** [functionality]
**So that** [business value]

**Acceptance Criteria:**

**Core Functionality:**
- [Primary behavior 1]
- [Primary behavior 2]
- [Expected workflow outcome]

**Input Validation:**
- [Field requirement 1]
- [Data format constraint 2]
- [Business rule validation 3]

**User Experience:**
- [Navigation behavior]
- [Feedback mechanism]
- [Error message display]

**Security & Access Control:**
- [Authentication requirement]
- [Authorization rule]
- [Data isolation rule]

**Data Integrity:**
- [Uniqueness constraint]
- [Required relationship]
- [Data consistency rule]

**Error Handling:**
- [Error scenario 1 → Expected message]
- [Error scenario 2 → Expected behavior]
- [Fallback behavior]

Example: Complete User Story

**As a** venue manager
**I want** to edit existing venue details
**So that** I can keep venue information accurate and up-to-date

**Acceptance Criteria:**

**Core Functionality:**
- User can modify venue name, address, capacity, and venue type
- Changes are saved when user clicks "Update Venue" button
- User sees updated information immediately after save
- Venue's UpdatedAt timestamp is automatically updated
- Other users see the updated venue information

**Input Validation:**
- Venue name is required (1-200 characters)
- Address is required (1-500 characters)
- Capacity must be positive integer (1-100,000)
- Cannot change venue name to match existing venue in tenant
- All validation rules from creation apply to updates

**User Experience:**
- Form pre-populates with current venue data
- "Save" button is disabled if no changes made
- "Cancel" button discards changes and returns to venue details
- Success message shows "Venue updated successfully"
- Loading state shown while saving changes
- Unsaved changes warning if user navigates away

**Security & Access Control:**
- Only authenticated users with 'venue-manager' or 'admin' role can edit
- User can only edit venues within their tenant
- Edit permission checked before displaying edit form
- API validates user permissions and tenant context

**Data Integrity:**
- UpdatedAt timestamp reflects actual save time
- Venue ID and CreatedAt fields cannot be modified
- Tenant association cannot be changed
- Venue type must exist and be active

**Error Handling:**
- "Venue not found" if venue deleted by another user
- "Permission denied" if user loses edit permissions
- "Another user modified this venue" for concurrent edits
- Network errors show retry option
- Field validation errors shown inline with guidance

Quality Standards

Clarity Requirements

User stories must be understandable by all stakeholders

✅ **Clear Language:**
- Use business terminology, not technical jargon
- Avoid implementation details (no class names, database schemas)
- Focus on user value and business outcomes
- Write from user's perspective

❌ **Unclear Examples:**
- "Update the VenueEntity in the database"
- "Call the UpdateVenueAsync method"
- "Implement PUT /api/venues/{id} endpoint"

Testability Standards

Every acceptance criterion must be objectively verifiable

✅ **Testable Criteria:**
- "User sees success message after venue creation"
- "Form validation prevents submission with empty name field"
- "API returns 403 error for unauthorized venue access"

❌ **Non-testable Criteria:**
- "User has good experience creating venues"
- "Form is user-friendly"
- "System performs well"

Completeness Checklist

**Story Review Checklist:**
□ Core functionality clearly defined
□ All input validation rules specified
□ User experience patterns documented
□ Security requirements explicit
□ Data integrity constraints listed
□ Error scenarios covered
□ Success criteria measurable
□ Edge cases considered
□ Dependencies identified
□ Acceptance criteria atomic (one concept per bullet)

Independence Guidelines

**Story Independence:**
- Each story delivers standalone business value
- Story can be developed and deployed independently
- Minimal dependencies on other stories
- Clear definition of "done"

**Dependency Management:**
- Explicit prerequisites listed
- Shared components identified
- Integration points documented
- Testing coordination planned

Multi-Tenant Considerations

Tenant Isolation Requirements

**Standard Tenant Security Criteria:**
- User can only access data within their tenant
- API validates tenant context from JWT claims
- Database queries automatically filter by tenant ID
- Cross-tenant data access is prevented
- Error messages don't leak information about other tenants

Tenant-Specific Validation

**Tenant Context Validation:**
- Resource uniqueness validated within tenant scope
- Business rules applied per tenant configuration
- User permissions evaluated within tenant context
- Audit logs include tenant information
- Data export/import respects tenant boundaries

Story Estimation Patterns

Complexity Indicators

**Simple Story (1-2 points):**
- Single entity CRUD operation
- Minimal validation rules
- Standard UI patterns
- No external integrations

**Medium Story (3-5 points):**
- Multiple entity relationships
- Complex validation logic
- Custom UI components needed
- Basic third-party integration

**Complex Story (8+ points):**
- Cross-service coordination
- Advanced security requirements
- Performance optimization needed
- Major architectural changes

Split Indicators

**Story Should Be Split When:**
- Multiple acceptance criteria categories are extensive
- Development estimate exceeds sprint capacity
- Multiple personas involved
- Cross-team dependencies required
- Testing spans multiple environments

These patterns ensure user stories provide clear guidance for development, testing, and product validation while maintaining focus on user value and business outcomes.