comentar-tarea
Agregar un comentario a un work item de Azure DevOps (queda en el Historial / Discusión de la tarjeta) y, si hace falta, leer los comentarios existentes. Usar cuando se pida "comentá en la #NNNN", "de
SKILL.md.claude/skills/comentar-tarea/SKILL.md
GitHubComentar tarea (comentarios en Azure)
Tablero local (
DEC-006): si el proyecto usa el tablero local, «el board» escerebro-digital/<modulo>/backlog/y se opera conbin/tablero-local.py, con los mismos GATEs y sin MCP (detalle:backlog/README.mddel módulo). Con Azure DevOps, Jira u otro tablero, las operaciones se traducen con la tabla deintegracion-azure-mcp/00-index.md.
Permite leer y dejar comentarios en un work item. En Azure DevOps el
comentario de una tarjeta se escribe en el campo Historial / Discusión
(System.History).
Regla de oro
- GATE de TABLERO (duro). La tarjeta debe pertenecer al tablero autorizado (org
{{AZURE_ORG}}· proyecto{{AZURE_PROYECTO}}· team{{AZURE_TEAM}}); antes de postear enSystem.Historyverificá el destino y, si es otro tablero, no escribas y mostrá la advertencia ([[tablero-autorizado]]). - Leer es libre; escribir con confirmación. Antes de postear, mostrar el texto y a qué
#IDva, y esperar tu OK — mostrar y postear son pasos distintos, no el mismo turno. Los sellos de auditoría de un lote ([[planificar-lote]]) se publican con el "sí" del cierre del lote: la tabla del cierre muestra el veredicto de cada tarjeta, y el sello es el molde fijo de abajo con esos valores. - Sin PHI en el comentario (marcadores
<persona>,<identificador>… en su lugar). Español. - No inventar: si el comentario afirma un dato duro sin confirmar, marcarlo
⚠. - Un comentario es sólo un comentario. La escritura lleva
System.Historyy ningún otro campo. Colar un cambio de Estado, de Etiquetas o de Descripción en la misma llamada es editar la tarjeta con otro nombre, y en una tarjeta congelada eso está prohibido ([[cambios-en-el-backlog]] §4). - Bien formateado, siempre (ver «Formato», abajo). Un comentario que se lee como un muro no lo lee nadie, y entonces no avisa nada.
Flujo
- (Opcional) Leer el hilo:
get_work_item_commentsdel#ID. - Redactar el comentario en español, sin PHI, en HTML con el molde que corresponda.
- Mostrar el comentario como se va a ver —no el HTML crudo, que nadie puede evaluar— y
la tarjeta destino (
#ID). - Con tu OK, postear:
update_work_itemsobre el campoSystem.History—y sólo ese— (así queda en la discusión de la tarjeta).
Nota: si el servidor MCP expone una herramienta específica para comentar un work item, se usa esa; si no, el mecanismo estándar de Azure es
System.Historyvíaupdate_work_item.
Formato: que se lea bien en Azure
Azure toma el comentario como HTML. Un texto plano con saltos de línea llega pegado en un
solo renglón: Azure descarta los saltos. Y el markdown (**, -, #, las comillas
invertidas) se ve literal. Por eso todo comentario se arma en HTML, con las mismas etiquetas que
la Descripción ([[checklists/mapa-campos-azure]]):
| Para | Se usa | No se usa |
|---|---|---|
| El renglón de arriba, que dice de qué se trata | <p><b>…</b></p> |
<h1> / <h2>: Azure ya pone el título de la tarjeta |
| Secciones | <h3>, con un <hr> antes de cada <h3> que viene después de otro contenido |
Secciones pegadas: sin el <hr> no se ve dónde termina una |
| Prosa | <p> |
Texto suelto entre etiquetas |
| Datos cortos (rama, commit, veredicto) | <ul><li><b>Nombre:</b> valor</li></ul> |
Una línea larga con todo separado por · |
| Comparar cosas en columnas | <table>, con <th> en la fila de títulos |
Espacios para alinear: en HTML se pierden |
| Líneas que lee una máquina (el sello) | Una por renglón, separadas con <br> |
Cambiarles el texto |
Marcadores (<persona>, <veredicto>) |
<persona> |
<persona> sin escapar: el navegador se lo come y desaparece sin aviso |
Nada de estilos inline (style=, colores, tamaños de letra): Azure los filtra o los muestra
distinto según el tema, claro u oscuro.
En los moldes, todo lo que va entre < > se reemplaza por el dato real. Antes de
mostrar el comentario se revisa que no quede ninguno: un marcador sin reemplazar no se
postea, porque en la tarjeta se lee como si fuera el dato. La excepción son los marcadores
de PHI (<persona>, <documento>…): ésos van a propósito, en lugar del dato real.
Las @menciones. Escribir @Nombre como texto no avisa a nadie: Azure sólo notifica si
la mención va como enlace con el identificador de la persona,
<a href="#" data-vss-mention="version:2.0,<id-de-la-persona>">@Nombre</a>. El
identificador sale del campo System.AssignedTo que devuelve el MCP. Si no se puede obtener,
se escribe el nombre en negrita y se avisa que la notificación no sale, para que se le
avise por otro lado. ⚠ A confirmar en el primer uso real que el MCP devuelve ese identificador.
El sello de auditoría ([[auditar-tarea]], [[auditar-historia]]), cuando se pidió una
auditoría, llega como bloque de texto plano. Es constancia, no barrera: nadie lo exige para
arrancar el desarrollo. No se reescribe: bin/verificar-sello lo lee buscando líneas
exactas, como Rev auditado: N, sobre el texto sin etiquetas. Sólo se lo formatea para que no quede
en un renglón: la primera línea en <p><b>…</b></p> y el resto una por renglón con <br>,
con el mismo texto, espacios incluidos. Lo único que no se postea es lo que en el bloque de
la skill va después de <-: son notas para quien lee la skill, no para la tarjeta. Ejemplo
lleno, del sello de [[auditar-tarea]]:
<p><b>Auditoria de Tarea - auditar-tarea</b></p>
<p>Veredicto: COMPLETA<br>
Fecha: AAAA-MM-DD<br>
Rev de la Tarea auditada: 7<br>
Historia padre: #<ID><br>
Rev de la Historia padre: 12<br>
Escenarios del padre encontrados: 4<br>
Hallazgos: 0 (el detalle, en el reporte)<br>
Pendientes a confirmar:<br>
- Ninguno</p>
Tarjeta congelada: acá sí se escribe
Una tarjeta en un sprint y ya tomada (Estado distinto de New) queda congelada: no se le
edita nada, sólo se comenta. Esta skill es por donde pasa todo lo que la IA quería cambiar
sobre ella: el DIFF propuesto va como comentario, con @mención a quien la tiene, y
aplicarlo lo decide una persona. Detalle: [[cambios-en-el-backlog]] §4.
Sirve para cualquier motivo: que cambió el documento funcional, que una auditoría encontró un hueco, o que a un equivalente le falta completar un campo.
Molde del cambio propuesto:
<p><b>Cambio propuesto</b> · la tarjeta está en el sprint y ya tomada, así que no se editó</p>
<p><a href="#" data-vss-mention="version:2.0,<id-de-la-persona>">@<persona></a>, <por qué hace falta el cambio: cambió el documento funcional · la auditoría encontró un hueco · le falta un campo>. Revisalo antes de seguir trabajando sobre esta tarjeta.</p>
<hr>
<h3>Qué cambiaría</h3>
<ul>
<li><b>Se agrega:</b> <qué, con su regla [RN-…]></li>
<li><b>Se modifica:</b> <qué: valor actual → valor nuevo, con su regla></li>
<li><b>Se quita:</b> <qué, o «nada»></li>
</ul>
<hr>
<h3>De dónde sale</h3>
<p><documento y versión, auditoría o pedido que lo origina></p>
<p><b>Aplicarlo o no lo decide una persona:</b> a mano en Azure, o en un ítem nuevo si lo que cambió es el pedido.</p>
Se escribe «se agrega / se modifica / se quita», no + ~ -: los símbolos le sirven al que ya
sabe leer un DIFF, y esta tarjeta la lee un funcional también. Las tres líneas van siempre,
aunque alguna diga «nada»: así se ve que se revisó.
Ejemplo lleno del renglón de la @mención y de una línea: «@‹persona›, cambió el documento funcional. Revisalo antes de seguir trabajando sobre esta tarjeta.» · «Se modifica: código por defecto 02 → 03 [RN-…-13]».
Comentario de cierre de desarrollo
Los datos duros los lee un script.
bin/datos-cierre.py --repo <worktree> --base <base> --id <ID>devuelve rama, último commit, cantidad de commits, archivos y carpetas tocadas, si está pusheada, el respaldoevidencia/<ID>y el link para abrir el Merge Request; lo que no pudo leer lo dice. La prosa del resumen técnico la pone esta skill con el resumen del worker; los datos no se escriben de memoria.
Lo aprendido no se queda en el comentario. Si el desarrollo confirmó o descubrió algo del negocio (una respuesta a un pendiente, una regla precisada), eso va al Cerebro por la Consulta Interactiva de Decisión de [[cerebro-orquestador]], no sólo a la tarjeta. El comentario lo lista en «Pendientes a confirmar» o en «Conocimiento para el Cerebro»; el Cerebro lo guarda. Y lo que el desarrollo mostró de la aplicación —qué módulo quedó construido y qué expone, un bug con su causa, una deuda aceptada— va a
<modulo>/aplicacion/(mapa.md,aprendizajes.md,deuda.md), con el#IDy el Merge Request como fuente.
Cuando termina el desarrollo de una Tarea, quien lo terminó deja constancia en la tarjeta: qué rama, qué Merge Request y qué se hizo. Así la tarjeta cuenta sola cómo se resolvió, sin tener que ir a buscarlo al código.
| Cuándo | Cuando la Tarea llega al Merge Request —o se pushea la rama, si el equipo mergea en local—: paso 7 del [[orquestador-desarrollo]], o al preparar la entrega en un desarrollo a mano ([[desarrollo]]). Después de que corrieron las verificaciones, porque el comentario informa su veredicto |
| En qué tarjetas | En cada Tarea que ese desarrollo cerró. La Historia padre no se comenta: el comentario ya la nombra, y repetirlo en el padre llena su hilo de ruido |
| Quién lo postea | Quien tiene el tablero: el orquestador, con el resumen del worker; en un desarrollo a mano, la misma sesión que programó |
| Confirmación | La de siempre: se muestra y se espera el "sí". Si terminan varias Tareas juntas, se muestran todos los comentarios juntos y un "sí" cubre exactamente ese lote, como en [[sincronizar-backlog]] |
Los datos duros salen del repositorio, nunca de la memoria. La rama y el último commit, de
git. El link del Merge Request, leído de GitLab por el MCP, sólo lectura: el comentario
nunca abre ni toca un Merge Request. Los tests, de la lista «Tests a escribir PRIMERO» y de
los commits test(rojo) del historial de trabajo (la rama evidencia/<ID>, subida a origin). Los
veredictos, de lo que devolvieron las verificaciones.
La parte en prosa —qué se hizo, cambios que rompen, lo que quedó afuera— sale de la
descripción del Merge Request, que ya tiene esos bloques ([[desarrollo]],
merge-request.md). Si no hay Merge Request, sale del resumen final del worker, y el
comentario lo dice: «según el resumen del desarrollo». Lo que no se pudo leer se escribe
⚠ sin dato: una línea vacía no se rellena con lo esperable.
Molde:
<p><b>Desarrollo terminado</b> · Tarea #<id> · Historia #<id-del-padre></p>
<ul>
<li><b>Rama:</b> <rama> (<pusheada | ⚠ sin pushear>)</li>
<li><b>Merge Request:</b> <a href="<link-del-merge-request>">!<número></a></li>
<li><b>Último commit:</b> <hash corto></li>
<li><b>Fecha:</b> <AAAA-MM-DD></li>
</ul>
<hr>
<h3>Qué se hizo</h3>
<p><dos o tres líneas en criollo: qué cambia para el que usa el sistema></p>
<hr>
<h3>Resumen técnico</h3>
<ul>
<li><b>Slice:</b> <slice></li>
<li><b>Contrato:</b> <endpoints tocados, y qué cambió en el openapi.yaml></li>
<li><b>Tests:</b> <N> de <M> ítems de «Tests a escribir PRIMERO», cada uno con su rojo antes del verde, verificado sobre el historial de trabajo</li>
<li><b>Commits:</b> <cantidad, agrupados por importancia (alrededor de 10)> en el Merge Request (último commit <hash corto> de la rama de la Tarea) · <N> commits de trabajo, verificados antes de reorganizar, en la rama evidencia/<ID> de origin</li>
<li><b>Cambios que rompen:</b> <ninguno | cuáles | ⚠ sin dato></li>
<li><b>Dependencias nuevas:</b> <ninguna | cuáles | ⚠ sin dato></li>
</ul>
<hr>
<h3>Verificaciones</h3>
<table>
<tr><th>Control</th><th>Qué contesta</th><th>Veredicto</th></tr>
<tr><td>Quién verificó</td><td>¿Otro agente que el que programó (DEC-005)?</td><td><motor> v<versión> · <modelo o worktree></td></tr>
<tr><td>verificar-tdd</td><td>¿Hubo rojo antes del verde?</td><td><veredicto></td></tr>
<tr><td>Revisión de código</td><td>¿Está bien escrito?</td><td><veredicto></td></tr>
<tr><td>auditar-codigo</td><td>¿Cumple la Tarea, sin PHI ni secretos?</td><td><veredicto></td></tr>
</table>
<hr>
<h3>Lo que quedó afuera</h3>
<ul>
<li><qué no se hizo, y por qué | «Nada» | ⚠ sin dato></li>
</ul>
<hr>
<h3>Pendientes a confirmar</h3>
<ul>
<li>⚠ <el hueco o el gris> · <qué se hizo mientras tanto> · <qué hace falta para cerrarlo, y quién lo define></li>
</ul>
Cómo se llenan los casos que no son el feliz, sin cambiar la forma:
| Si… | Se escribe |
|---|---|
| La rama no se pusheó | (⚠ sin pushear) en lugar de (pusheada) |
| El desarrollo tocó dos slices | Los dos, y el motivo: <slice-1> y <slice-2>, porque … |
| El contrato no cambió | sin cambios en el contrato |
| No se cubrieron todos los ítems de la lista | <N> de <M>, y abajo cuáles faltan. No es un desarrollo terminado: se dice |
| No hay Merge Request | todavía no abierto en lugar del link, y la prosa lleva «según el resumen del desarrollo» |
| Un control no corrió | SIN DATOS en su fila. No es aprobado |
| Un control dio hallazgos | HALLAZGO y, en una línea abajo de la tabla, cuántos y cuál es el bloqueante |
| La fuente dice que no quedó nada afuera | <li>Nada</li>. La sección no se borra: su ausencia no dice si se revisó |
| No se pudo leer un dato | ⚠ sin dato |
| Hay número de Merge Request pero no su link | !15 (⚠ sin link), sin <a>: un enlace con href vacío o inventado lleva a ningún lado |
| No se sabe el slice | ⚠ sin dato. El slice es uno de los declarados en [[contexto-proyecto]] (<slice-1> · <slice-2> · <slice-n>); nunca el nombre del producto |
| No quedó ningún pendiente | <li>Ninguno</li>, si el worker lo dijo. La sección no se borra |
«Ninguno» y «Nada» son datos, no valores por defecto. Se escriben sólo si la descripción
del Merge Request o el resumen del desarrollo lo dicen. Si no lo dice nadie, va ⚠ sin dato:
un «ninguno» que nadie afirmó es una afirmación inventada. Lo mismo con «Qué se hizo»: se
copia de la fuente, no se redacta a partir del título de la Tarea.
Barreras del cierre.
- Un veredicto que no corrió es
SIN DATOS, no aprobado. Si una verificación dio hallazgos, el comentario lo dice: no se omite para que la tarjeta quede prolija. - El comentario no cambia el Estado. Pasar la Tarea a Resolved o Closed no lo hace la IA: la tarjeta ya está congelada y el cierre es una decisión de una persona.
- Sin PHI, sin secretos, sin tokens, y sin logs pegados: es el mismo cuidado que en la descripción del Merge Request, y el comentario queda en Azure para siempre.
Pendientes a confirmar
Un hueco o un gris de una Tarea —un dato que falta, una decisión ⚠ que el Cerebro no
cerró, un caso que la lista de tests no cubre, un hallazgo de una auditoría que alguien pidió—
no frena el desarrollo y no se vuelve a preguntar en el momento. Se deja escrito en la
tarjeta, para que se resuelva más adelante y se vea al cerrarla (decisión de diseño del template).
| Qué hace quien programa | Lo que no depende del gris lo hace. Lo que depende de él no lo inventa: lo deja afuera, o toma el camino que la Tarea ya escribe, y lo anota como pendiente. Frena sólo si el gris impide toda la Tarea |
| Dónde queda | En la sección «Pendientes a confirmar» del comentario de cierre (molde de arriba), que ya pide su "sí" y no suma un turno. Si no hay comentario de cierre —el desarrollo se cortó, o el pendiente sale de una auditoría—, va en un comentario propio con el molde de abajo |
| Qué lleva cada uno | Qué es el gris · qué se hizo mientras tanto · qué hace falta para cerrarlo y quién lo define. Si ya tiene P-nnn en el Cerebro, se cita |
Molde del pendiente suelto:
<p><b>Pendientes a confirmar</b> · Tarea #<id></p>
<ul>
<li>⚠ <el hueco o el gris> · <qué se hizo mientras tanto> · <qué hace falta para cerrarlo, y quién lo define></li>
</ul>
Un pendiente que se resuelve se responde en otro comentario —«Pendiente resuelto: ‹cuál›, ‹cómo›»—: el original no se edita, así queda la traza.
Antes de cerrar una Tarea: revisar los pendientes
Cuando se va a cerrar una Tarea —pasarla a Resolved o Closed, o al estado de revisión
al terminar un desarrollo—, antes se leen sus
comentarios (get_work_item_comments, lectura libre) y su Descripción, y se listan los
pendientes que no tienen su «Pendiente resuelto»:
- los de los comentarios «Pendientes a confirmar» y del comentario de cierre;
- de los sellos de auditoría, sólo el más reciente (uno posterior deja sin efecto al viejo);
- los
⚠que siguen en «Datos a confirmar» de la Descripción.
La lista va en el primer aviso del cierre:
«Antes de cerrar la #NNNN: quedan 2 pendientes sin resolver en sus comentarios — ‹uno›, ‹otro›. ¿Querés cerrarla igual?»
- No frena el cierre: lo decide la persona, pero con los pendientes a la vista.
- Los GATES del cierre no cambian. Pasar a Resolved o Closed es edición destructiva: dos "sí" en turnos distintos, y la lista de pendientes va en el primero. Si la Tarea está congelada (en un sprint y ya tomada), la IA no le cambia el Estado: muestra los pendientes y la cierra una persona ([[cambios-en-el-backlog]] §4).
- Sin pendientes, se dice: «No quedan pendientes en los comentarios.»
- Si no se pudieron leer los comentarios, es SIN DATOS, y se dice: no es «no hay pendientes».
- Si no hubo ninguna auditoría y ningún pendiente, no pasa nada: el chequeo da vacío y se sigue.
Contexto adicional
- Herramientas MCP y flujo de escritura con confirmación: [[integracion-azure-mcp/04-automatizar-con-ia]] · [[integracion-azure-mcp/00-index]].
- Etiquetas HTML que acepta Azure, con los esqueletos de la Descripción: [[checklists/mapa-campos-azure]].
- Tarjeta congelada (en un sprint y ya tomada): [[cambios-en-el-backlog]] §4.
- Pendientes a confirmar y su revisión antes de cerrar: §«Pendientes a confirmar», arriba.
- Aviso de cambios (drift): el protocolo de [[cambios-en-el-backlog]] usa esta skill para el comentario con @mención cuando un doc cambió y hay que avisar a quien trabaja la tarjeta (junto con la etiqueta
cambio-pendiente-lectura, que en una tarjeta congelada no se pone).
Ejemplo (genérico)
"Dejá una nota en la #NNNN avisando que falta confirmar la versión." La skill redacta el comentario —
<p>Queda ⚠ pendiente confirmar la versión afectada antes de pasar a QA.</p>—, lo muestra como se va a ver, y con tu OK lo postea en el Historial de la tarjeta. Sin datos reales de por medio.