---
name: azure-pbi-plan
description: Convierte un PBI o Bug de Azure Boards en un plan de implementación anclado al código real, sin escribir ni una línea. Lee el work item, recorre el repositorio, propone el enfoque y adjunta el plan al propio work item. Úsala antes de implementar algo que toca varias capas, o cuando quieras validar el enfoque con el equipo antes de gastar dos días.
version: 1.0.0
license: CC-BY-4.0
updated: 2026-08-17
---

# Azure Boards: planificar antes de implementar

El plan no es burocracia: es la única oportunidad barata de descubrir que el
enfoque estaba mal. Reescribir un párrafo cuesta cinco minutos; reescribir tres
capas, dos días.

Esta skill escribe un plan **prospectivo** —en futuro, lo que *se hará*— y lo
deja donde el equipo lo pueda discutir.

## Lo que este flujo no hace

Nada de esto, bajo ninguna circunstancia:

- tocar código de producción o de test
- compilar o ejecutar la batería de pruebas
- crear commits, hacer push o abrir pull requests

Las únicas escrituras son el fichero del plan y —previa confirmación— su subida
a Azure DevOps. Un flujo de planificación que "de paso" implementa deja de ser
un plan y pasa a ser un cambio sin revisar.

## 1. Leer el work item

```bash
curl -s -u ":$PAT" \
  "https://dev.azure.com/$ORG/$PROJECT/_apis/wit/workitems/$ID?fields=System.Title,System.Description,Microsoft.VSTS.Common.AcceptanceCriteria,System.WorkItemType&api-version=7.1"
```

Tres detalles que ahorran un rehacer:

- El tipo sale de `System.WorkItemType`, **no se supone** por el nombre de rama.
- El título se usa **literal**. Reescribirlo rompe la trazabilidad con el tablero.
- La descripción y los criterios vienen en HTML: hay que limpiar etiquetas.

Si los criterios llegan vacíos o son ambiguos, ese es el hallazgo: dilo y pregunta.
Un plan construido sobre requisitos inventados valida un enfoque que nadie pidió.

## 2. Recorrer el código, no la memoria

Por cada criterio de aceptación, localiza y **lee** el código que habrá que tocar:

- El caso de uso concreto (comando o consulta, su handler, su DTO). Ahí aterriza
  casi todo.
- Las entidades de dominio implicadas, sobre todo si los criterios hablan de
  estados o transiciones.
- Las integraciones externas: la interfaz y quién la implementa.
- La persistencia: mapeos y si hace falta migración.
- El test hermano más parecido, para copiar su estructura en vez de inventar una.

Cada afirmación del plan sobre el código actual apunta a un fichero que existe,
idealmente con línea: `Application/Orders/…/GetOrderHandler.cs:42`. Lo que no
hayas verificado, se dice que no está verificado.

**Extender antes que crear.** El plan que añade una carpeta nueva cuando ya
existe un handler que hace el 80% es un plan que nadie va a querer mantener.

## 3. Escribir el plan

Estructura mínima, sin secciones de relleno:

| Sección | Qué responde |
|---|---|
| Contexto y problema | Qué se pide y por qué, en 3-6 líneas |
| Criterios de aceptación | Copiados literales y numerados, para referenciarlos |
| Estado actual del código | Qué existe ya y dónde, con rutas reales |
| **Enfoque propuesto** | La solución y **por qué esa**; las descartadas, con su motivo |
| **Cambios por capa** | Cada fichero marcado como *crear* o *modificar* |
| Tests | Un test por criterio siempre que se pueda |
| Riesgos | Datos ya corruptos, contratos, rendimiento, decisiones pendientes |
| **Checklist** | Ordenado y marcable: es lo que se sigue al implementar |
| Verificación | La prueba manual concreta: endpoint, payload, consulta |

Las tres en negrita no se eliminan nunca. El resto, si no aporta, fuera.

**Escrito en futuro.** «Se añadirá», «habrá que modificar». Un plan que se lee
como un changelog es un plan escrito después de implementar, y entonces ya no
sirve para decidir nada.

Y el criterio de calidad: **otra persona tiene que poder ejecutarlo sin rehacer
el análisis.** Si para entender el paso 4 hay que volver a leer el mismo código
que tú leíste, el plan no está terminado.

## 4. Adjuntarlo al work item

Adjuntar es publicar: lo verá el equipo. **Pide confirmación explícita antes.**

Son dos llamadas, y la primera sola no hace nada visible:

```bash
# 1. Subir el fichero -> la respuesta trae .url
curl -s -u ":$PAT" -H "Content-Type: application/octet-stream" -X POST \
  "https://dev.azure.com/$ORG/$PROJECT/_apis/wit/attachments?fileName=plan.md&api-version=7.1" \
  --data-binary @plan.md

# 2. Enlazarlo: sin esto, el adjunto existe pero nadie lo ve
curl -s -u ":$PAT" -H "Content-Type: application/json-patch+json" -X PATCH \
  "https://dev.azure.com/$ORG/$PROJECT/_apis/wit/workitems/$ID?api-version=7.1" \
  -d '[{"op":"add","path":"/relations/-","value":{
        "rel":"AttachedFile","url":"<url del paso 1>",
        "attributes":{"comment":"Plan de implementación"}}}]'
```

Si devuelve `401` o `403`, el PAT tiene ámbito de solo lectura: adjuntar exige
**Work Items (Read & Write)**. El fichero local no se toca, se dice qué pasó y se
ofrece adjuntarlo a mano. No reintentar a ciegas.

## Reglas

- El plan lo lee el equipo entero: nada de cadenas de conexión, tokens ni datos
  personales dentro.
- Si el análisis revela que el work item está mal planteado, eso **es** el
  entregable. Un plan honesto que dice «esto no se puede hacer sin decidir X
  antes» vale más que uno completo que se lo inventa.
- Crear la rama, si se ofrece, es lo último y es opcional. Y ahí termina: no
  sigue ninguna implementación.