El fichero, entero
Esto es exactamente lo que descargas: sin resúmenes ni recortes.
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
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:
# 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.