---

name: user-story-writing description: Write effective user stories that capture requirements from the user's perspective. Create clear stories with detailed acceptance criteria to guide development and define done.

User Story Writing

Overview

Well-written user stories communicate requirements in a user-focused way, facilitate discussion, and provide clear acceptance criteria for developers and testers.

When to Use

• Breaking down requirements into development tasks
• Product backlog creation and refinement
• Agile sprint planning
• Communicating features to development team
• Defining acceptance criteria
• Creating test cases

Instructions

1. User Story Format

# User Story Template

**Title:** [Feature name]

**As a** [user role/persona]
**I want to** [action/capability]
**So that** [business value/benefit]

---

## User Context

- User Role: [Who is performing this action?]
- User Goals: [What are they trying to accomplish?]
- Use Case: [When do they perform this action?]

---

## Acceptance Criteria

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

Example:
Given a user is logged in and viewing their cart
When they add a product to cart
Then the cart count increases and success message appears

---

## Definition of Done

- [ ] Code written and peer reviewed
- [ ] Unit tests written (>80% coverage)
- [ ] Integration tests passing
- [ ] Acceptance criteria verified
- [ ] Documentation updated
- [ ] No console errors or warnings
- [ ] Performance acceptable
- [ ] Accessibility requirements met
- [ ] Security review completed
- [ ] Product owner approval

---

## Additional Details

**Story Points:** 5 (estimate of effort)
**Priority:** High
**Epic:** [Parent feature]
**Sprint:** Sprint 23
**Assignee:** [Developer]
**Dependencies:** [Other stories this depends on]

---

## Notes

- Any additional context or considerations
- Edge cases to consider
- Performance constraints
- Accessibility requirements
- Security considerations

2. Story Refinement Process

# Story refinement and quality gates

class UserStoryRefinement:
    QUALITY_GATES = {
        'Independent': 'Story can be implemented independently',
        'Negotiable': 'Details can be discussed and refined',
        'Valuable': 'Delivers clear business value',
        'Estimable': 'Team can estimate effort',
        'Small': 'Can be completed in one sprint',
        'Testable': 'Clear acceptance criteria'
    }

    def evaluate_story(self, story):
        """Assess story quality using INVEST criteria"""
        assessment = {}

        for criterion, description in self.QUALITY_GATES.items():
            assessment[criterion] = self.check_criterion(story, criterion)

        return {
            'story_id': story.id,
            'assessment': assessment,
            'ready_for_development': all(assessment.values()),
            'issues': self.identify_issues(story),
            'recommendations': self.provide_recommendations(story)
        }

    def check_criterion(self, story, criterion):
        """Evaluate against specific INVEST criterion"""
        checks = {
            'Independent': lambda s: len(s.dependencies) == 0,
            'Negotiable': lambda s: len(s.acceptance_criteria) > 0,
            'Valuable': lambda s: len(s.business_value) > 0,
            'Estimable': lambda s: s.story_points is not None,
            'Small': lambda s: s.story_points <= 8,
            'Testable': lambda s: len(s.acceptance_criteria) > 0 and all(
                ac.get('test_case') for ac in s.acceptance_criteria
            )
        }
        return checks[criterion](story)

    def refine_story(self, story):
        """Guide refinement discussion"""
        return {
            'story_id': story.id,
            'refinement_agenda': [
                {
                    'topic': 'Clarify scope',
                    'questions': [
                        'What exactly does the user need?',
                        'What's NOT included?',
                        'Are there edge cases?'
                    ]
                },
                {
                    'topic': 'Define acceptance criteria',
                    'questions': [
                        'How do we know when it's done?',
                        'What are success criteria?',
                        'What should fail gracefully?'
                    ]
                },
                {
                    'topic': 'Technical approach',
                    'questions': [
                        'How will we implement this?',
                        'Are there dependencies?',
                        'What are the risks?'
                    ]
                },
                {
                    'topic': 'Estimation',
                    'questions': [
                        'How much effort?',
                        'Any unknowns?',
                        'Buffer needed?'
                    ]
                }
            ],
            'outputs': [
                'Refined story description',
                'Detailed acceptance criteria',
                'Technical approach identified',
                'Story points estimate',
                'Dependencies listed',
                'Team agreement on scope'
            ]
        }

3. Acceptance Criteria Examples

Story: As a customer, I want to save payment methods so I can checkout faster

Acceptance Criteria:

Scenario 1: Add a new payment method
  Given I'm logged in
  And I'm on the payment settings page
  When I click "Add payment method"
  And I enter valid payment details
  And I click "Save"
  Then the payment method is saved
  And I see a success message
  And the new method appears in my saved list

Scenario 2: Edit existing payment method
  Given I have saved payment methods
  When I click "Edit" on a method
  And I change the expiration date
  And I click "Save"
  Then the changes are saved
  And other fields are unchanged

Scenario 3: Delete a payment method
  Given I have multiple saved payment methods
  When I click "Delete" on a method
  And I confirm the deletion
  Then the method is removed
  And my default method is updated if needed

Scenario 4: Error handling
  Given I enter invalid payment information
  When I click "Save"
  Then I see an error message
  And the method is not saved
  And I'm returned to the form to correct

Scenario 5: Security
  Given the payment form is displayed
  When I view the page source
  Then I don't see full payment numbers (PCI compliance)
  And credit card data is encrypted
  And the connection is HTTPS

---

Non-Functional Requirements:
  - Performance: Form save must complete in <2 seconds
  - Usability: Form must be completable in <3 steps
  - Reliability: 99.9% uptime for payment service
  - Accessibility: WCAG 2.1 AA compliance
  - Security: PCI DSS Level 1 compliance

4. Story Splitting

// Breaking large stories into smaller pieces

class StorySpitting {
  SPLITTING_STRATEGIES = [
    'By workflow step',
    'By user role',
    'By CRUD operation',
    'By business rule',
    'By technical layer',
    'By risk/complexity',
    'By priority'
  ];

  splitLargeStory(largeStory) {
    return {
      original_story: largeStory.title,
      original_points: largeStory.story_points,
      strategy: 'Split by workflow step',
      split_stories: [
        {
          id: 'US-201',
          title: 'Add payment method - Form UI',
          points: 3,
          description: 'Build payment form UI with validation',
          depends_on: 'None',
          priority: 'First'
        },
        {
          id: 'US-202',
          title: 'Add payment method - Backend API',
          points: 5,
          description: 'Create API endpoint to save payment method',
          depends_on: 'US-201',
          priority: 'Second'
        },
        {
          id: 'US-203',
          title: 'Add payment method - Integration',
          points: 3,
          description: 'Connect form to API, handle responses',
          depends_on: 'US-202',
          priority: 'Third'
        },
        {
          id: 'US-204',
          title: 'Add payment method - Security hardening',
          points: 2,
          description: 'PCI compliance, encryption, data protection',
          depends_on: 'US-202',
          priority: 'Critical'
        }
      ],
      total_split_points: 13,
      complexity_reduction: 'From 13pt single story to 5pt max',
      benefits: [
        'Faster feedback cycles',
        'Parallel development possible',
        'Easier testing',
        'Clearer scope per story'
      ]
    };
  }
}

5. Story Estimation

Story Pointing Framework:

1 Point: Trivial
  - Update label text
  - Add CSS class
  - Simple config change
  - Time: <2 hours

2 Points: Very small
  - Add simple field to form
  - Update error message
  - Simple validation
  - Time: 2-4 hours

3 Points: Small
  - Create single page/component
  - Add basic API endpoint
  - Simple integration
  - Time: 4-8 hours

5 Points: Medium
  - Create feature with multiple interactions
  - Build API with multiple endpoints
  - Complex business logic
  - Time: 1-2 days

8 Points: Large
  - Feature spanning multiple pages
  - Complex integration
  - Multiple technical challenges
  - Time: 2-3 days

13 Points: Very large (TOO BIG - Split it!)
  - Should be split into smaller stories
  - Or elevated to epic
  - Time: >3 days

---

Estimation Tips:
  - Use relative sizing (compare to known stories)
  - Consider unknowns and risks
  - Include non-coding time (testing, docs)
  - Account for team skill level
  - Be transparent about assumptions
  - Re-estimate after learning

Best Practices

✅ DO

• Write from the user's perspective
• Focus on value, not implementation
• Create stories small enough for one sprint
• Define clear acceptance criteria
• Use consistent format and terminology
• Have product owner approve stories
• Include edge cases and error scenarios
• Link to requirements/business goals
• Update stories based on learning
• Create testable stories

❌ DON'T

• Write technical task-focused stories
• Create overly detailed specifications
• Write stories that require multiple sprints
• Forget about non-functional requirements
• Skip acceptance criteria
• Create dependent stories unnecessarily
• Write ambiguous acceptance criteria
• Ignore edge cases
• Create too large stories
• Change stories mid-sprint without discussion

User Story Tips

• Keep stories focused on user value
• Use story splitting when >5 points
• Always include acceptance criteria
• Review stories with team before sprint
• Update definitions of done as team learns