Azure Devops Boards

Azure DevOps Boards Skill

Manage and analyze Azure DevOps Boards using az boards and az devops CLI commands.

Discovery-First Rule

ALWAYS discover before acting. Never assume project names, team names, iteration paths, or work item IDs.

# Set default organization
az devops configure --defaults organization="$ORG_URL"

# Discover projects
az devops project list --output json --query "value[].{name:name, id:id, state:state}"

# Discover teams in a project
az devops team list --project "$PROJECT" --output json --query "[].{name:name, id:id}"

Parallel Execution Requirement

ALL independent operations MUST run in parallel using background jobs (&) and wait.

for project in $(echo "$projects" | jq -c '.[]'); do
  {
    name=$(echo "$project" | jq -r '.name')
    az boards query --wiql "SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject]='$name' AND [System.State]='Active'" --project "$name" --output json
  } &
done
wait

Helper Functions

# Query work items with WIQL
query_work_items() {
  local project="$1" wiql="$2"
  az boards query --wiql "$wiql" --project "$project" --output json
}

# Get work item details
get_work_item() {
  local id="$1"
  az boards work-item show --id "$id" --output json \
    --query "{id:id, title:fields.\"System.Title\", state:fields.\"System.State\", type:fields.\"System.WorkItemType\", assignedTo:fields.\"System.AssignedTo\".displayName, priority:fields.\"Microsoft.VSTS.Common.Priority\", storyPoints:fields.\"Microsoft.VSTS.Scheduling.StoryPoints\", iteration:fields.\"System.IterationPath\"}"
}

# List iterations (sprints)
list_iterations() {
  local project="$1" team="$2"
  az boards iteration team list --project "$project" --team "$team" --output json \
    --query "[].{name:name, path:path, startDate:attributes.startDate, finishDate:attributes.finishDate, timeFrame:attributes.timeFrame}"
}

# Get iteration work items
get_iteration_items() {
  local project="$1" iteration="$2"
  az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.AssignedTo],[Microsoft.VSTS.Scheduling.StoryPoints] FROM WorkItems WHERE [System.TeamProject]='$project' AND [System.IterationPath]='$iteration'" --project "$project" --output json
}

Common Operations

1. Sprint Status Overview

# Get current sprint work items
current_iteration=$(az boards iteration team list --project "$PROJECT" --team "$TEAM" --output json \
  --query "[?attributes.timeFrame=='current'] | [0].path" -o tsv)

az boards query --wiql "SELECT [System.Id],[System.Title],[System.State],[System.AssignedTo],[Microsoft.VSTS.Scheduling.StoryPoints],[System.WorkItemType] FROM WorkItems WHERE [System.IterationPath]='$current_iteration' ORDER BY [System.State]" \
  --project "$PROJECT" --output json

2. Burndown Analysis

# Get sprint scope and completion
az boards query --wiql "
  SELECT [System.Id],[System.State],[Microsoft.VSTS.Scheduling.StoryPoints]
  FROM WorkItems
  WHERE [System.IterationPath]='$ITERATION'
  AND [System.WorkItemType] IN ('User Story','Bug')
" --project "$PROJECT" --output json

# Summarize by state
# Parse results to calculate: Total points, Completed points, Remaining points, In Progress points

3. Backlog Health

# Unassigned items in backlog
az boards query --wiql "
  SELECT [System.Id],[System.Title],[System.WorkItemType],[Microsoft.VSTS.Common.Priority]
  FROM WorkItems
  WHERE [System.TeamProject]='$PROJECT'
  AND [System.State]='New'
  AND [System.AssignedTo]=''
  ORDER BY [Microsoft.VSTS.Common.Priority]
" --project "$PROJECT" --output json

# Items without estimates
az boards query --wiql "
  SELECT [System.Id],[System.Title]
  FROM WorkItems
  WHERE [System.TeamProject]='$PROJECT'
  AND [System.WorkItemType]='User Story'
  AND [Microsoft.VSTS.Scheduling.StoryPoints]=''
  AND [System.State] NOT IN ('Closed','Removed')
" --project "$PROJECT" --output json

4. Team Velocity

# Get completed story points per iteration
iterations=$(az boards iteration team list --project "$PROJECT" --team "$TEAM" --output json \
  --query "[?attributes.timeFrame=='past'] | [-3:]")
for iter in $(echo "$iterations" | jq -c '.[]'); do
  {
    path=$(echo "$iter" | jq -r '.path')
    echo "Sprint: $path"
    az boards query --wiql "SELECT [Microsoft.VSTS.Scheduling.StoryPoints] FROM WorkItems WHERE [System.IterationPath]='$path' AND [System.State]='Closed' AND [System.WorkItemType]='User Story'" --project "$PROJECT" --output json
  } &
done
wait

5. Work Item Aging

# Find old items still in active state
az boards query --wiql "
  SELECT [System.Id],[System.Title],[System.CreatedDate],[System.State],[System.AssignedTo]
  FROM WorkItems
  WHERE [System.TeamProject]='$PROJECT'
  AND [System.State] IN ('Active','New')
  AND [System.CreatedDate] < @Today-30
  ORDER BY [System.CreatedDate]
" --project "$PROJECT" --output json

Output Format

Present results as a structured report:

Azure Devops Boards Report
══════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Common Pitfalls

1. WIQL syntax: WIQL uses single quotes for string values, not double quotes. Field names with dots must be in square brackets.
2. Organization default: Always set az devops configure --defaults organization= before running commands.
3. Story Points field: The field name varies by process template -- Agile uses Microsoft.VSTS.Scheduling.StoryPoints, Scrum uses Microsoft.VSTS.Scheduling.Effort.
4. Iteration paths: Iteration paths include the project name prefix (e.g., Project\Sprint 1). Use the full path from discovery.
5. Query limits: WIQL queries return a max of 200 work items by default. Use --top parameter for larger result sets.