---
name: azure-pbi-implement
description: Lleva un PBI o Bug de Azure Boards de su ID a un árbol de trabajo listo para revisar - lee el work item, crea la rama, implementa contra los criterios de aceptación, pasa build y tests, actualiza el changelog y escribe la descripción de la PR. Nunca commitea, ni hace push, ni abre la pull request. Úsala cuando arranques un work item por su número.
version: 1.0.0
license: CC-BY-4.0
updated: 2026-08-17
---

# Azure Boards: implementar un work item

El ciclo completo de un work item, con una frontera dura al final:

```
leer work item → rama → plan → implementar → build + test
→ changelog → nota de PR → parar
```

**Aquí no se commitea.** Ni `git add`, ni `git commit`, ni `git push`, ni abrir
la PR. El árbol se deja modificado y la persona decide. Un agente que commitea
solo convierte cada error en algo que hay que deshacer del historial en lugar de
descartar con un `git checkout`.

## 0. Antes de nada

Dos comprobaciones que cuestan cinco segundos y evitan un desastre:

- El PAT vive en `.env` y se usa solo como `curl -u ":$PAT"`. Nunca se imprime,
  nunca se registra, nunca acaba en un fichero que se commitea.
- `.gitignore` cubre `.env`, `pr-*.md` y `plan-*.md`. Si falta alguno, se añade
  **antes** de generar nada. Es la única escritura permitida antes de implementar.

## 1. El work item manda

```bash
curl -s -u ":$PAT" \
  "https://dev.azure.com/$ORG/$PROJECT/_apis/wit/workitems/$ID?\$expand=relations&api-version=7.1"
```

De ahí salen el tipo (`System.WorkItemType`, no se supone), el título exacto, la
descripción, los criterios de aceptación y las tareas hijas
(`System.LinkTypes.Hierarchy-Forward`), que luego se enlazan a la PR.

Resume el work item antes de tocar nada. Si los criterios están vacíos, para y
pregunta: implementar contra requisitos imaginados es la forma más cara de
descubrir que no era eso.

## 2. Rama desde la base, siempre

```bash
git fetch origin
git switch -c "$PREFIJO/pbi_$ID" origin/develop   # o bug_$ID
```

Si ya existe, `switch` a ella. Ramificar de una rama local desactualizada es el
origen del 90% de los conflictos que aparecen «de la nada» en la PR.

## 3. Calibrar el esfuerzo

No todo merece un plan de tres páginas:

- **Modo rápido** — dos criterios o menos, una sola capa tocada. Se confirma en
  una línea y se va.
- **Modo plan** — por defecto. Se presenta el plan derivado de los criterios y se
  espera confirmación antes de escribir código.

Detectar mal la complejidad hacia abajo cuesta un rehacer; hacia arriba, solo
cuesta un mensaje de más. Ante la duda, plan.

## 4. Implementar

El `CLAUDE.md` del repo manda sobre arquitectura, nombres y convenciones de test.
Esta skill no impone estilo: lo lee del proyecto.

Después, en este orden, y **no se sigue si alguno falla**:

```bash
dotnet build
dotnet test
```

Un test que falla no es «un detalle a mirar luego»: es la implementación sin terminar.

## 5. Changelog

La línea del work item bajo `[UNRELEASED]`: `Added` si es un PBI, `Fixed` si es
un Bug.

```
- [x][Product Backlog Item <id>: <título exacto>](https://dev.azure.com/<org>/<proyecto>/_workitems/edit/<id>)
```

Este fichero **sí** se commitea, cuando la persona commitee.

## 6. La nota de la PR

Un fichero `pr-<id>.md` que no se versiona y que contiene lo que irá en la
descripción de la pull request:

- El título exacto y los criterios de aceptación
- Qué cambió, por fichero y por capa
- **Cómo verificarlo**: el endpoint, el payload, la consulta concreta

Ese tercer punto es el que decide si tu PR se revisa hoy o el jueves. Un revisor
que tiene que averiguar cómo probar el cambio lo deja para luego.

## 7. Parar y contar

El informe final: rama creada, ficheros tocados, resultado de build y tests, ruta
de la nota de PR. Y decirlo con todas las letras: **no se ha commiteado nada**.

Si más adelante piden la PR, entonces —y solo entonces— se crea, enlazando el
work item y sus tareas hijas:

```bash
curl -s -u ":$PAT" -H "Content-Type: application/json" -X POST \
  "https://dev.azure.com/$ORG/$PROJECT/_apis/git/repositories/$REPO/pullrequests?api-version=7.1" \
  -d '{ "sourceRefName": "refs/heads/…", "targetRefName": "refs/heads/develop",
        "title": "(develop) Product Backlog Item <id>: <título exacto>",
        "description": "…", "workItemRefs": [{"id":"<id>"}] }'
```

El cuerpo se construye con `jq` o `python -c`. Escapar markdown a mano dentro de
JSON funciona hasta la primera comilla, y falla en silencio.

## Por qué la frontera

Crear la PR es una acción hacia fuera: notifica al equipo, entra en la cola de
revisión de otras personas y ya no se deshace sin ruido. El código sin commitear
se descarta con un comando. Por eso la línea está donde está.