boards-backlog-audit

Backlog Health Check

This Skill reads a team's requirements-level backlog, compares each item against Microsoft Learn recommendations, and lists problems and fixes.Read-only, no modifications: to fix fields, use boards-work-item-write(each item requires user confirmation); to fill in Sprints, use work-iterations。

Microsoft Learn documentation referenced:

Project selection

If the user has provided a project name (for example "Contoso project"), use it directly without calling the project list API.
If not provided, ask the user to provide it once.
If still not provided, list the projects for the user to choose from:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/projects?%24top=500&api-version=7.1"

Do not continue until the user provides or selects a project.

Team selection

If the user has provided a team name, use it directly without calling the team list API.
If not provided, ask the user to provide it once.

If still not provided, list the teams of the selected project for the user to choose from:

curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/_apis/projects/{project}/teams?%24top=500&api-version=7.1"

Do not continue until the user provides or selects a team.

Connection and authentication

Always use curl to call the Azure DevOps REST API directly; each command carries its own authentication parameters.

Organization: read the environment variable AZURE_DEVOPS_ORG(organization name, for example contoso). If not set, ask the user once; if the user gives a URL, extract the organization name from https://dev.azure.com/{org} or https://{org}.visualstudio.com .
Token: send the PAT with Basic authentication:-u ":$AZURE_DEVOPS_PAT"; if only AZURE_DEVOPS_EXT_PATis set (the variable used by the Azure CLI azure-devops extension), use that instead. When using a Microsoft Entra ID token instead, switch to -H "Authorization: Bearer $AZURE_DEVOPS_TOKEN". If neither is set, ask the user to set AZURE_DEVOPS_PAT in their own terminal and retry, and stop. Read tokens only from environment variables: do not ask the user to paste a token into the conversation, and do not print or write it to a file.
PAT permission scopes：Work Items (Read)、Project and Team (Read)。
Encoding: project, team, and work item type names in paths must be URL-encoded (spaces written as %20); in query strings, write $ as %24(for example %24expand) to avoid shell expansion.
Errors: HTTP 401, 403, 203, or an HTML login page in the response means the token is invalid, expired, or lacks permissions; report it and stop. HTTP 404 means the organization, project, or team name is wrong.
Windows PowerShell: call curl.exe(not the curl alias); write environment variables as $env:AZURE_DEVOPS_PAT; PowerShell does not support <<'EOF', so first write the JSON body to a temporary file, then send it with --data-binary "@body.json" .

Steps

Determine the project and team according to the rules above.
Get the process configuration. Estimate fieldAlwaysuse typeFields.Effort.referenceName(for example Microsoft.VSTS.Scheduling.Effort、Microsoft.VSTS.Scheduling.StoryPoints、Microsoft.VSTS.Scheduling.Size), do not guess based on the process name:
```
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/work/processconfiguration?api-version=7.1"
```
portfolioBacklogs[].workItemTypes[].name are portfolio-level types such as Feature and Epic.
Get the work item IDs in the backlog (in backlog order):
```
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/{team}/_apis/work/backlogs/Microsoft.RequirementCategory/workItems?api-version=7.1"
```
ID at workItems[].target.id. If the list is empty, explain that this team's backlog has no items, and only perform the Iteration check in step 7.

Retrieve all fields and relations with batch calls (at most 200 IDs per call; split into batches if there are more).$expand cannot be specified together with fields , so do not include fields：

curl -sS -u ":$AZURE_DEVOPS_PAT" -X POST -H "Content-Type: application/json" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/wit/workitemsbatch?api-version=7.1" \
  -d '{"ids":[101,102],"$expand":"Relations","errorPolicy":"Omit"}'

Fields with empty values will not appear in fields .

For each System.WorkItemTypethat appears in the response (for example, there will be two kinds when a Bug is also on the backlog), retrieve the state and fields once for each:
```
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/wit/workitemtypes/{type}/states?api-version=7.1"
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/_apis/wit/workitemtypes/{type}/fields?api-version=7.1"
```
In Progressthe state is category is InProgress of name(do not hard-code names such as Active、Committed ). The field list value[].referenceName is used to determine whether this type has an estimate field and Microsoft.VSTS.Common.AcceptanceCriteria; for types without that field (for example, an Issue in a custom process), skip that check and note it in the report.

Check item by item (“In Progress” =System.State belongs to the In Progress state from step 5):

Check	How to determine
Missing estimate	The type has an estimate field, but `fields` does not contain that field
Missing acceptance criteria	The type has `Microsoft.VSTS.Common.AcceptanceCriteria`, but it has no value, or it is an empty string after removing HTML tags and whitespace
No parent item	`fields` does not contain `System.Parent`
In Progress but unassigned	In Progress, and there is no `System.AssignedTo`
In Progress but no development link	In Progress, and `relations[]` does not contain `rel` is `ArtifactLink`、`url` a relation that starts with one of the following
Backlog too large	The number of items from step 3 exceeds 999

Development links are determined by the url prefix, not by display names such as attributes.name :vstfs:///Git/Commit/（commit）、vstfs:///Git/Ref/（branch）、vstfs:///Git/PullRequestId/（PR）、vstfs:///GitHub/Commit/、vstfs:///GitHub/PullRequest/、vstfs:///GitHub/Branch/。vstfs:///Build/Build/(Integrated in build) does not count, because it does not mean someone is developing it.

When there is System.Parent , you may optionally make another batch call to retrieve the parent item's System.WorkItemType; list separately any parent item that is not an aggregation-level type (for example, attached under another PBI).

Get the team's Iterations:
```
curl -sS -u ":$AZURE_DEVOPS_PAT" \
  "https://dev.azure.com/$AZURE_DEVOPS_ORG/{project}/{team}/_apis/work/teamsettings/iterations?api-version=7.1"
```
Count attributes.timeFrame as future ; if there are fewer than 6, list it as a problem.timeFrame For the Iteration that is current , if attributes.finishDate is earlier than today, it means the team has no Sprint covering today, so also list it as a problem.startDate、finishDate may be null; for this kind of Iteration, additionally note “no dates set”.
Present it in the format below.

Suggested fixes

Check	Suggestion
Missing estimate	Use relative sizing estimates during backlog refinement; both Velocity and Forecast require estimates. If you only want to forecast by count, Learn recommends entering 1 for each item.
Missing acceptance criteria	Every item must have clear acceptance criteria and a definition of done so the team can estimate and test it.
No parent item	Map unassigned requirements to an appropriate Feature (the backlog's Mapping pane, or use `boards-work-item-write` to set a parent item).
In progress but unassigned	Assign each item to only one owner; when work is split among multiple people, split it into multiple items.
In progress but no development link	From the work item's Development section, create a branch, or reference the work item ID in commits and PRs so changes can be traced.
Not enough future Sprints	Learn recommends creating at least six Iterations, covering the next three to six months; use `work-iterations` to create them according to the existing cadence and assign them to the team.
Backlog too large	The create-your-backlog documentation states that each backlog displays at most 999 items (the Services object limits page says 10,000); it is recommended to add a team and move some items out, or close outdated items.

Present the results

Title: project, team, number of backlog items, reference name of the estimation field, check time (user's local time zone).
Summary table：

Check Number of issues Status

Missing estimates 12 ⚠️

Future Sprints 3 (recommended ≥ 6) ❌

Mark ✅ when there is no issue, ⚠️ when there is an issue, and ❌ when there are insufficient Iterations or the backlog is too large; mark skipped checks with ➖ and note the reason (for example, "Issue type has no acceptance criteria field").
Item details: one subsection per check with issues; first write the fix recommendation, then list the items in a table: ID (link https://dev.azure.com/{organization}/{project}/_workitems/edit/{ID}), type, title, status, assigned to. Order them according to the backlog order in step 3 (batch responses are sorted by ID); when there are more than 20 entries, list only the first 20 and state the total, then ask whether to list the remaining items.
Iteration: list the names and start and end dates of current and future Iterations (YYYY/MM/DD）。
Last line: checked {N} items,{M} items have at least one issue.