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

Type	When to Use
User Story	Default for new functionality, features, or user-facing changes
Issue	Technical debt, infrastructure work, or non-functional improvements
Bug	Defects, broken functionality, or behavior that doesn't match expectation

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

Required Fields by Work Item Type

User Story Fields

Field	Description
Title	Concise description of the feature
Description	"As a [user], I want [action] so that [benefit]" format
Story Points	Fibonacci estimate (1, 2, 3, 5, 8, 13)
Acceptance Criteria	Specific, measurable, verifiable criteria
Iteration Path	Sprint assignment

Issue Fields

Field	Description
Title	Concise description of the technical work
Description	"We need [capability] to [purpose]" format
Story Points	Fibonacci estimate (1, 2, 3, 5, 8, 13)
Acceptance Criteria	Definition of done for the technical work
Iteration Path	Sprint assignment

Bug Fields

Field	Description
Title	Brief description of the defect
Repro Steps	Step-by-step instructions to reproduce
System Info	Environment, browser, OS where bug occurs
Expected Behavior	What should happen
Actual Behavior	What actually happens
Severity	1-Critical, 2-High, 3-Medium, 4-Low
Priority	1-High, 2-Medium, 3-Low
Iteration Path	Sprint assignment

Description Formats

User Story Format

For user-facing functionality:

markdown

As 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):

markdown

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

## Additional Context

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

Bug Description Format

markdown

## 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)

Points	Complexity	Time Indication
1	Trivial task, can be done in minutes	Less than half a day
2	Small task, straightforward implementation	Half day to one day
3	Medium task, some complexity	One to two days
5	Larger task, moderate complexity	Two to three days
8	Complex task, requires significant effort	Three to five days
13	Very complex, should consider splitting	One week or more - split it!

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

Pattern	Example
User can [action] and sees [result]	User can upload a file and sees a success message
System returns [response] when [condition]	System returns 404 when resource not found
API responds within [X]ms for [Y] concurrent users	API responds within 200ms for 100 concurrent users
Error message '[text]' displays when [condition]	Error "File too large" displays when file > 10MB
[Feature] supports [specific formats/values]	Upload accepts JPG, PNG, and GIF files up to 10MB

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

markdown

### 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

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

Description Structure

markdown

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

#### Additional Context

- Bullet point context
- Another point

#### Dependencies

Related items or references.

Acceptance Criteria Structure

markdown

### 1. Category Name

- [ ] First criterion
- [ ] Second criterion

### 2. Another Category

- [ ] Third criterion
- [ ] Fourth criterion

Example Field Specifications

User Story Example

json

{
  "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

json

{
  "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

json

{
  "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

code

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

Issue Format

code

We need [capability] to [purpose].

Acceptance Criteria Format

code

[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