gonzalezpazmonica/azure-devops-queries

Skill: azure-devops-queries

Skill transversal. Léela SIEMPRE antes de cualquier operación con Azure DevOps.

Constantes de esta skill

# Leer siempre desde el entorno (configuradas en .claude/.env y CLAUDE.md raíz)
ORG_URL="${AZURE_DEVOPS_ORG_URL}"          # https://dev.azure.com/MI-ORGANIZACION
ORG_NAME="${AZURE_DEVOPS_ORG_NAME}"        # MI-ORGANIZACION
PAT_FILE="${AZURE_DEVOPS_PAT_FILE}"        # $HOME/.azure/devops-pat
API_VERSION="${AZURE_DEVOPS_API_VERSION}"  # 7.1

---

1. Autenticación

Opción A — Azure CLI (preferida)

az devops configure --defaults organization=$ORG_URL project=$PROJECT_NAME
export AZURE_DEVOPS_EXT_PAT=$(cat $PAT_FILE)
az devops project list --output table

Opción B — REST API directa con curl

PAT=$(cat $PAT_FILE)
B64_PAT=$(echo -n ":$PAT" | base64)
curl -H "Authorization: Basic $B64_PAT" \
     -H "Content-Type: application/json" \
     "$ORG_URL/$PROJECT/_apis/..."

---

2. Regla Crítica: Filtrar SIEMPRE por IterationPath

⚠️ SIEMPRE incluir filtro [System.IterationPath] UNDER @CurrentIteration en las queries WIQL, salvo que se pida explícitamente una query cross-sprint.

Sin este filtro, las queries devuelven TODOS los work items del proyecto desde el inicio, lo que satura el contexto y degrada la calidad de las respuestas.

---

3. Queries WIQL Fundamentales

Detalle: @references/wiql-queries.md

Cinco queries básicas para la mayoría de casos:

1. Items del sprint actual con horas
2. Bugs activos por severidad
3. Items por persona (carga actual)
4. PBIs para sprint planning
5. Items completados en el sprint

Ejecutar con CLI:

az boards query --wiql "SELECT..." --project "$PROJECT_NAME" --output json | jq '.workItems[].id'

---

4. Operaciones CLI Frecuentes

# Listar sprints del equipo
az boards iteration team list --project "$PROJECT_NAME" --team "$TEAM_NAME" --output table

# Obtener work item por ID
az boards work-item show --id XXXX --output json

# Actualizar horas
az boards work-item update --id XXXX \
  --fields "Microsoft.VSTS.Scheduling.CompletedWork=8"

---

5. REST API Directa — Endpoints Clave

BASE="$ORG_URL/$PROJECT/_apis"
BASE_TEAM="$ORG_URL/$PROJECT/$TEAM/_apis"

# Capacidades, días off, board, iteración actual
GET $BASE_TEAM/work/teamsettings/iterations/{iterationId}/capacities?api-version=$API_VERSION
GET $BASE_TEAM/work/teamsettings/iterations/{iterationId}/teamdaysoff?api-version=$API_VERSION
GET $ORG_URL/$PROJECT/_odata/v4.0-preview/WorkItemSnapshot?\$filter=...
GET $BASE_TEAM/work/teamsettings/iterations?\$timeframe=current&api-version=$API_VERSION

---

6. Campos WIQL — Referencia Rápida

Detalle: @references/wiql-fields.md

Campos principales: System.Id, System.Title, System.State, System.AssignedTo, System.WorkItemType, System.IterationPath, Microsoft.VSTS.Scheduling.StoryPoints, Microsoft.VSTS.Scheduling.RemainingWork, Microsoft.VSTS.Common.Activity, Microsoft.VSTS.Common.Priority, Microsoft.VSTS.Common.Severity

---

7. Errores Comunes y Soluciones

| Error | Solución | |-------|----------| | TF400813: The user is not authorized | Regenerar PAT con scopes correctos | | VS403501: The query returned too many results | Añadir filtro UNDER @CurrentIteration | | TF26027: Iteration not found | Verificar con az boards iteration team list | | 400 Bad Request en capacities API | Usar team ID en lugar de nombre | | Resultados vacíos en @CurrentIteration | Configurar sprint activo en AzDevOps |

---

Referencias

→ Patrones WIQL: references/wiql-patterns.md → Campos detallados: references/wiql-fields.md → Analytics OData: references/odata-patterns.md