---
name: azure-devops-tickets
description: |
  Use this skill when the user wants to manage Azure DevOps work items —
  Bugs, User Stories, Tasks, Features, Epics. Triggers on:
  - "create a work item / story / bug / task / feature / epic"
  - mentions of work item IDs in AB#NNNN format
  - sprint planning operations: "what's in the current sprint", "move to backlog"
  - bulk operations: "create work items for each story in this PRD"
  - PR-to-work-item linking
  
  Do NOT use for Jira work — that's a different skill (jira-ticket-manager).
---

# Azure DevOps Tickets

You help users manage Azure DevOps Boards work items following Evoke's
conventions. You apply the right template per work item type, fill required
fields, and never create incomplete tickets.

## Required fields by work item type

### User Story
- **Title:** Imperative voice, <100 chars
- **Description:** Acceptance criteria + technical notes (use template)
- **Story Points:** Fibonacci (1, 2, 3, 5, 8, 13, ?)
- **Priority:** 1 (highest) - 4 (lowest)
- **Area Path:** Match to existing Areas in the project
- **Iteration Path:** Current sprint or backlog
- **Tags:** Always `evoke-platform`. Add domain tags as appropriate.

### Bug
- **Title:** "Bug: [short description]"
- **Repro Steps:** Numbered list
- **System Info:** Environment, browser/OS, version
- **Severity:** 1-Critical / 2-High / 3-Medium / 4-Low
- **Priority:** 1-4 (independent of severity)
- **Found In:** Build/version where the bug appeared

### Task
- **Title:** Imperative, action-oriented
- **Description:** Steps to complete
- **Activity:** Development / Testing / Documentation / etc.
- **Original Estimate:** Hours
- **Parent:** Link to parent User Story (most tasks should have a parent)

### Feature
- **Title:** Outcome-oriented, broader than a story
- **Description:** Business value + scope (in/out)
- **Target Date:** Quarterly granularity
- **Parent:** Often linked to an Epic

### Epic
- **Title:** Initiative-level, business outcome
- **Description:** Strategic context, success metrics, scope
- **Start/Target Date:** Multi-quarter

## Workflow

### Single work item creation

1. If the user provides enough context, restate what you'll create:
   > "I'll create a User Story:
   > - Title: [proposed title]
   > - Description: [first 2 lines of description]
   > - Story Points: [estimated]
   > - Priority: [1-4]
   > - Area: [path]
   > - Iteration: [sprint or backlog]
   >
   > Confirm or adjust?"

2. Wait for confirmation or edits.
3. Create via the Azure DevOps MCP tool.
4. Report back with the work item ID and URL.

### Insufficient context

If the user says "create a story for the auth feature" without enough detail:

> "I can create that story. Quick questions:
> 1. What's the user value? (As a [persona], I want [capability], so that
>    [benefit])
> 2. Acceptance criteria — 2-3 Given/When/Then bullets?
> 3. Story points estimate?"

Wait for answers. Then proceed.

### Bulk creation from a PRD or list

1. Parse the input into structured work items
2. Show a preview table:

| # | Type | Title | Story Points | Parent |
|---|------|-------|--------------|--------|
| 1 | User Story | Login with email/password | 3 | EPIC-001 |
| 2 | User Story | Reset forgotten password | 5 | EPIC-001 |
| ... | ... | ... | ... | ... |

3. Get explicit confirmation: "Confirm I should create all [N] items?"
4. Create one at a time, reporting progress every 5 items.
5. At the end, output a summary:
   - Created [N] work items
   - All linked to parent: [link]
   - Bulk view: [query URL]

### Updates

When updating an existing work item:
1. Fetch the current state via MCP
2. Show the proposed diff:
   > "Updating AB#1234:
   > - Status: New → Active
   > - Assigned To: (unassigned) → @user
   > - Tags: + 'in-progress'"
3. Confirm before applying.

### Status transitions

State machine for User Story:

State machine for Bug:

Validate the transition is legal before attempting:
- Don't move from "Closed" to "Active" — that's a reopen, requires comment
- Don't skip "Resolved" when going from "Active" → "Closed"
- For "Removed", require a reason in the comment

### Linking work items

Common relationships:
- Story → Parent: Feature or Epic
- Task → Parent: User Story
- Bug → Related: User Story (cause) or Test Case (validation)

When creating a child item, suggest the parent if context implies it:
> "This task seems related to AB#1234 (the auth story). Link as parent?"

## Templates (use exactly)

### User Story description template

```markdown
## User Story

As a [persona]
I want [capability]
So that [benefit]

## Acceptance Criteria

- [ ] **Given** [context]
      **When** [action]
      **Then** [outcome]

- [ ] **Given** [context]
      **When** [action]
      **Then** [outcome]

## Technical Notes

- API endpoints affected:
- Database changes:
- Dependencies:
- Estimated story points: [X]

## Out of Scope

- 

## Definition of Done

- [ ] Code merged to main
- [ ] Unit tests added (>80% coverage on new code)
- [ ] Integration tests pass
- [ ] Documentation updated
- [ ] Deployed to staging
- [ ] PM/QA acceptance

## Summary

[One-line description]

## Steps to Reproduce

1. 
2. 
3. 

## Expected Behavior

## Actual Behavior

## Environment

- App version:
- Browser/OS:
- User account/role:
- Time observed:

## Screenshots / Logs

[Attach or paste]

## Impact

- Users affected: [scope]
- Workaround available: [yes/no - describe]
- Severity: [1-Critical / 2-High / 3-Medium / 4-Low]

## MCP setup (one-time)

Before this skill works, the Azure DevOps MCP server needs to be configured. Add to `~/.config/claude-code/mcp.json`:

```json
{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@evoke/azure-devops-mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "${AZURE_DEVOPS_ORG}",
        "AZURE_DEVOPS_PROJECT": "${AZURE_DEVOPS_PROJECT}",
        "AZURE_DEVOPS_PAT": "${AZURE_DEVOPS_PAT}"
      }
    }
  }
}

export AZURE_DEVOPS_ORG="your-org-name"     # from dev.azure.com/{org}
export AZURE_DEVOPS_PROJECT="your-project"   # default project
export AZURE_DEVOPS_PAT="your-pat"           # Personal Access Token