---

name: story-writing description: "Use when creating user stories, writing acceptance criteria, or formatting work items for Azure DevOps. Triggers include create user story, write acceptance criteria, format work item, story points, bug report, technical issue, backlog item, and Azure DevOps work item."

Story Writing Skill

Overview

This skill provides guidelines for creating well-structured Azure DevOps work items including User Stories, Issues, and Bugs. It covers work item type selection, required fields, description formats, story point estimation, and acceptance criteria best practices.

---

Work Item Type Selection

Default to User Story unless the request clearly describes an issue or bug.

---

Required Fields by Work Item Type

User Story Fields

Issue Fields

Bug Fields

---

Description Formats

User Story Format

For user-facing functionality:

CopyAs a [type of user], I want to [action] so that [benefit].

## Additional Context

[Implementation constraints, dependencies, non-functional requirements, edge cases]

Technical Requirement Format

For infrastructure, refactoring, or backend work (Issues):

CopyWe need [technical capability] to [purpose/benefit].

## Additional Context

[Implementation constraints, dependencies, non-functional requirements, edge cases]

Bug Description Format

Copy## Expected Behavior

[What should happen]

## Actual Behavior

[What actually happens]

## Reproduction Steps

1. [First step]
2. [Second step]
3. [Step where bug occurs]

## Environment

- OS: [Operating system]
- Browser: [Browser and version]
- Version: [Application version]

---

Story Points Estimation (Fibonacci Scale)

Estimation Guidelines

• Maximum is 13 points - If larger, split into multiple stories
• Relative sizing - Compare to previously completed stories
• Include all work - Development, testing, code review, documentation
• Account for unknowns - Add buffer for research or exploration

When to Split Stories

Split a story when:

• Estimate exceeds 13 points
• Multiple distinct user outcomes exist
• Different technical components can be delivered independently
• Story spans multiple sprints

---

Acceptance Criteria Guidelines

Each criterion must be specific, measurable, and verifiable.

Good Patterns

Good Examples

• ✅ "Upload accepts JPG, PNG, and GIF files up to 10MB"
• ✅ "Error message displays when file exceeds 10MB"
• ✅ "Thumbnail generates at 150x150 pixels"
• ✅ "Page loads in under 2 seconds on 3G connection"
• ✅ "User receives email confirmation within 5 minutes"
• ✅ "Form validates email format before submission"
• ✅ "Search returns results within 500ms for up to 10,000 records"

Bad Examples (Avoid)

• ❌ "Performance is good"
• ❌ "User experience is intuitive"
• ❌ "System handles errors gracefully"
• ❌ "Code is clean"
• ❌ "Application is fast"
• ❌ "Design looks nice"
• ❌ "It works correctly"

Acceptance Criteria Structure Template

Copy### 1. Functional Requirements

- [ ] User can [specific action]
- [ ] System [specific behavior] when [condition]

### 2. Validation

- [ ] Input validates [specific rules]
- [ ] Error message "[text]" displays when [condition]

### 3. Performance

- [ ] [Action] completes within [X] seconds
- [ ] System supports [Y] concurrent users

### 4. Edge Cases

- [ ] System handles [edge case] by [behavior]

---

Markdown Formatting for Azure DevOps

Formatting Rules

1. Use Markdown format for all rich text fields
2. No bold fragments - Avoid **bold** within sentences; use headers instead
3. Use numbered section headers with checklists for acceptance criteria
4. Use plain paragraphs with markdown headers for descriptions

Description Structure

CopyAs a [user], I want [action] so that [benefit].

#### Additional Context

- Bullet point context
- Another point

#### Dependencies

Related items or references.

Acceptance Criteria Structure

Copy### 1. Category Name

- [ ] First criterion
- [ ] Second criterion

### 2. Another Category

- [ ] Third criterion
- [ ] Fourth criterion

---

Example Field Specifications

User Story Example

Copy{
  "fields": [
    {
      "name": "System.Title",
      "value": "Allow users to upload profile pictures"
    },
    {
      "name": "System.Description",
      "value": "As a registered user, I want to upload a profile picture so that other users can identify me.\n\n#### Additional Context\n\n- Support common image formats\n- Implement size restrictions for storage optimization",
      "format": "Markdown"
    },
    {
      "name": "Microsoft.VSTS.Scheduling.StoryPoints",
      "value": 5
    },
    {
      "name": "Microsoft.VSTS.Common.AcceptanceCriteria",
      "value": "### 1. Upload Functionality\n\n- [ ] User can select image from device\n- [ ] Upload accepts JPG, PNG, and GIF up to 10MB\n\n### 2. Validation\n\n- [ ] Error displays for unsupported formats\n- [ ] Error displays when file exceeds 10MB\n\n### 3. Display\n\n- [ ] Thumbnail generates at 150x150 pixels\n- [ ] Image displays on user profile",
      "format": "Markdown"
    },
    {
      "name": "System.IterationPath",
      "value": "ProjectName\\Sprint 1"
    }
  ]
}

Bug Example

Copy{
  "fields": [
    {
      "name": "System.Title",
      "value": "Login button unresponsive on mobile Safari"
    },
    {
      "name": "Microsoft.VSTS.TCM.ReproSteps",
      "value": "### Steps to Reproduce\n\n1. Open application on iOS Safari\n2. Enter valid credentials\n3. Tap Login button\n4. Observe button does not respond\n\n### Expected Behavior\n\nUser is authenticated and redirected to dashboard.\n\n### Actual Behavior\n\nButton tap is not registered; no action occurs.",
      "format": "Markdown"
    },
    {
      "name": "Microsoft.VSTS.TCM.SystemInfo",
      "value": "- Device: iPhone 14 Pro\n- OS: iOS 17.2\n- Browser: Safari 17.2\n- App Version: 2.3.1",
      "format": "Markdown"
    },
    {
      "name": "Microsoft.VSTS.Common.Severity",
      "value": "2 - High"
    },
    {
      "name": "Microsoft.VSTS.Common.Priority",
      "value": "1"
    }
  ]
}

Issue (Technical) Example

Copy{
  "fields": [
    {
      "name": "System.Title",
      "value": "Implement caching layer for API responses"
    },
    {
      "name": "System.Description",
      "value": "We need a Redis caching layer to reduce database load and improve response times.\n\n#### Additional Context\n\n- Current avg response time: 800ms\n- Target response time: 200ms\n- Expected cache hit ratio: 70%",
      "format": "Markdown"
    },
    {
      "name": "Microsoft.VSTS.Scheduling.StoryPoints",
      "value": 8
    },
    {
      "name": "Microsoft.VSTS.Common.AcceptanceCriteria",
      "value": "### 1. Implementation\n\n- [ ] Redis cache configured and connected\n- [ ] Frequently accessed endpoints use cache\n\n### 2. Performance\n\n- [ ] Cached responses return in under 100ms\n- [ ] Cache invalidation works correctly\n\n### 3. Monitoring\n\n- [ ] Cache hit/miss metrics available in dashboard",
      "format": "Markdown"
    }
  ]
}

---

Clarification Checklist

Before creating a work item, verify you have:

For User Stories

• Clear user type or persona
• Defined action the user wants to perform
• Stated benefit or purpose
• Unambiguous scope
• Enough information for acceptance criteria

For Bugs

• Expected behavior described
• Actual behavior described
• Reproduction steps provided
• Environment/system info available
• Severity assessment possible

For Issues

• Technical capability defined
• Purpose or benefit stated
• Scope boundaries clear
• Definition of done determinable

---

Quick Reference Card

Title Guidelines

• Concise and action-oriented
• Written from feature/capability perspective
• Avoids technical jargon when possible

Story Format

CopyAs a [user type], I want to [action] so that [benefit].

Issue Format

CopyWe need [capability] to [purpose].

Acceptance Criteria Format

Copy[Subject] [action/state] [measurable outcome] when [condition].

Story Points Quick Guide

• 1-2: Simple, well-understood tasks
• 3-5: Moderate complexity, some unknowns
• 8: Complex, multiple components
• 13: Very complex - consider splitting