Implementar Tarea

¿Qué hace Implementar Tarea?

Entrega un ticket de 1 punto como un PR para revisión, que contenga exactamente lo que pide el ticket y nada más.

Entrada

$ARGUMENTS

• Ticket, obligatorio: una clave del tracker (p. ej. ENG-123) o un ID local (p. ej. T-04). Si falta, lista los tickets listos (estado open, dependencias fusionadas), primero los de ruta crítica, y pregunta cuál tomar. En modo no supervisado, reporta bloqueado.
• --tasks <archivo>: el archivo de tareas local. Si no se proporciona, busca el *.tasks.md que contenga el ticket en la carpeta RFC local, ignorada por git, del proyecto (p. ej. .rfcs/), luego docs/rfcs/.
• --base <rama>: la rama desde la que empezar y como destino del PR. Por defecto es main. Una rama base que no sea main significa que el PR está apilado sobre el PR sin fusionar de otro ticket.
• --branch <nombre>: el nombre de la rama a usar. De lo contrario, sigue la regla de nomenclatura del paso 1.
• --feedback <pr>: no implementar; abordar los comentarios de revisión en un PR existente (consulta la última sección).
• --unattended: fuiste iniciado por un orquestador y nadie puede responder preguntas. Nunca preguntes; cuando tengas que preguntar, detente y explica en el informe. Haz tu trabajo en tu propio worktree.

Dónde viven el ticket y los archivos locales

• Tracker primero. Si el ticket tiene una clave de tracker (como argumento, o en el campo Tracker: del archivo de tareas), obténlo a través de la herramienta de tracker conectada (Linear, Jira, GitHub Issues, …). Cuando está publicado, el tracker es la fuente de verdad para el contenido del ticket; si está cancelado o completado allí, detente e informa.
• Archivo de tareas local en caso contrario, y para los campos que le faltan al issue del tracker (archivos, fuera de alcance). Los RFC y los archivos de tareas son documentos locales del desarrollador, no rastreados, por lo que existen solo en la carpeta principal del proyecto, no en un worktree. Si estás en un worktree, encuentra la carpeta principal con git worktree list (la primera entrada) y lee los archivos allí usando la ruta absoluta. Trata la carpeta principal como solo lectura: nunca edites, hagas checkout o ejecutes comandos git en ella.
• Nunca hagas commit de RFC, notas o archivos de tareas. Prepara los archivos por ruta explícita, no con git add -A.

1. Seleccionar el ticket

• Lee el ticket (ver arriba), incluyendo sus criterios de aceptación y dependencias. Si su tipo es spike, detente: los spikes producen una decisión, no un PR; apunta a /spike-task (no supervisado: reporta bloqueado).
• Una dependencia está satisfecha cuando su PR está fusionado en main (verifica el estado del PR con gh, o el estado de la dependencia pr-merged/done), o cuando la rama base es la propia rama de esa dependencia (apilamiento). Una dependencia de spike está satisfecha solo cuando está done, lo que significa que su decisión fue aprobada y el backlog refinado. Si alguna dependencia no está satisfecha, detente y di cuál.
• Asegúrate de que el árbol de trabajo esté limpio, haz fetch, y crea la rama desde el último origin/<base>.
• Nombre de la rama (a menos que se haya dado --branch): <usuario>/<slug-del-proyecto>/<rama-de-tarea>.
  • usuario: el prefijo de las ramas existentes del usuario si siguen este patrón, de lo contrario su inicio de sesión de GitHub (gh api user --jq .login).
  • slug-del-proyecto: del encabezado Project slug: del archivo de tareas, o el nombre del RFC en kebab case.
  • rama-de-tarea: la clave del tracker más un slug corto, p. ej. eng-123-add-v2-flag (la clave permite que las integraciones del tracker enlacen el PR), o t-04-add-v2-flag si no está publicado.
• Si estás trabajando directamente con el usuario (no supervisado), establece el estado del ticket a in progress en el archivo de tareas, y en el tracker si su integración con GitHub no lo hará.

2. Cargar solo lo que necesita el ticket

Lee el ticket, la sección del RFC en la que se basa, y los archivos que nombra. Luego traza el flujo real: llamantes, helpers existentes y las pruebas junto al código que cambiarás. Lee lo suficiente para entender completamente el problema, pero no cargues todo el RFC o el historial de la sesión; el ticket fue escrito para ser independiente. Si no lo es, eso es una brecha que reportar, no para adivinar.

3. Escribir las pruebas primero

Convierte cada criterio de aceptación en una prueba, usando el framework de pruebas, la ubicación y el estilo existentes del repositorio. Ejecútalas y confirma que fallan por la razón correcta. Una prueba enfocada por criterio es suficiente: no se necesitan nuevas utilidades de prueba, fixtures o helpers a menos que un patrón existente los requiera. Los tickets puramente mecánicos (p. ej. añadir una bandera) pueden no necesitar una prueba nueva si el criterio es verificado por pruebas existentes o el verificador de tipos; dilo en el PR.

4. Implementar el cambio completo más pequeño

"Completo" significa que cada criterio de aceptación pasa. "Más pequeño" significa nada más allá de eso. Esto sigue el enfoque ponytail; si un skill ponytail está instalado, cárgalo ahora en su nivel predeterminado y deja que gobierne este paso.

De lo contrario, toma la primera opción que funcione:

1. ¿Ya está cubierta la necesidad? Si el código existente ya satisface los criterios, detente y propón cerrar el ticket.
2. Reutiliza lo que ya tiene el código base: helpers, tipos, patrones.
3. Usa la biblioteca estándar, luego las características nativas de la plataforma (restricciones de BD, entradas HTML incorporadas, CSS antes que JS), luego las dependencias ya instaladas.
4. Solo entonces escribe código nuevo, lo mínimo que funcione.

Mientras lo escribes:

• Sin estructura especulativa. Sin interfaces con una sola implementación, sin fábricas para un solo producto, sin configuración para valores que nunca cambian, sin andamios "para después". Prefiere editar un archivo existente a crear uno nuevo.
• Coincide con el código circundante: nomenclatura, manejo de errores, estructura. El diff debería parecer que el código base lo escribió.
• Comentarios solo donde el código no puede hablar. No narres lo que hace el código, reafirmes el ticket, ni dejes código comentado o salidas de depuración. El único comentario que vale la pena añadir es en una simplificación deliberada: nombra el límite y cuándo actualizarlo, para que nadie lo "arregle" accidentalmente.
• Corrige errores en la raíz. Verifica cada llamante antes de cambiar una función compartida.
• Nunca minimices la seguridad. Validación de entrada en los límites de confianza, manejo de errores que evite la pérdida de datos, seguridad y accesibilidad básica se hacen siempre correctamente, incluso si el ticket no los detalla.

5. Proteger el alcance

Si el ticket resulta ser más grande de 1 punto (más de aproximadamente un día, aparece una segunda preocupación, o un criterio no se puede cumplir sin tocar áreas no relacionadas), detente. No hagas commit de nada más allá de lo limpio, explica lo que encontraste y propón una división como nuevos tickets para aprobación: escríbelos en el archivo de tareas cuando trabajes con el usuario, o en el informe cuando no estés supervisado. Los problemas no relacionados que notes van en las notas del PR, no en el diff. Nunca debilites ni reinterpretes un criterio de aceptación para que pase.

6. Verificar y abrir el PR

1. Ejecuta las pruebas, el linter y el verificador de tipos como lo hace el repositorio. Si el cambio tiene comportamiento en tiempo de ejecución y puedes ejecutar /verify, hazlo; de lo contrario, ejercita el comportamiento con los comandos de ejecución o verificación del proyecto.
2. Vuelve a leer el diff completo tú mismo: cada línea cambiada debe rastrearse hasta un criterio de aceptación. Elimina formato no relacionado, renombres y archivos extraviados, y asegúrate de que ningún archivo RFC o de tareas local se haya colado.
3. Haz commit siguiendo el estilo de commits del repositorio, haz push y abre el PR listo para revisión (no borrador, para que la automatización de revisión se ejecute, a menos que el usuario haya pedido un borrador) contra la rama base, usando templates/pr.md. Pon la clave del tracker en el título y enlaza el issue del tracker en la descripción. Si la base no es main, di sobre qué PR está apilado y que ese se fusiona primero. Si no puedes abrir PRs desde aquí, haz push de la rama e incluye el texto del PR en tu respuesta.
4. Si estás trabajando directamente con el usuario, establece el estado del ticket a pr-open (o pr-draft) y completa Branch / PR: en el archivo de tareas, y mueve el issue del tracker a su estado de revisión si su integración con GitHub no lo hará. No supervisado, deja los estados al orquestador.
5. Termina con el informe a continuación. Con un usuario presente, una versión de dos o tres líneas es suficiente.

Abordar comentarios de PR (--feedback)

Recibes un PR y una lista de elementos de revisión a abordar (enlaces a comentarios más qué hacer).

1. Obtén y haz checkout de la rama del PR en tu worktree. Lee el ticket y los elementos; lee el diff actual.
2. Aborda cada elemento con el cambio más pequeño que lo resuelva, bajo las mismas reglas del paso 4. Mantente dentro del alcance del ticket: si un elemento pide algo más allá de él, no lo construyas; repórtalo como un seguimiento.
3. Añade nuevos commits en lugar de enmendar o hacer force push, para que los revisores puedan ver qué cambió desde su revisión. Ejecuta las pruebas, luego haz push.
4. Responde en cada hilo de comentario abordado con una línea que diga qué cambió y el SHA corto del commit. Para elementos que te indicaron responder sin cambiar código, responde con el texto dado. Si concluyes que un elemento no debería cambiarse, no discutas en el hilo; déjalo y explica en tu informe.
5. Termina con el informe, usando done si cada elemento fue manejado, blocked en caso contrario.

Informe

Termina tu mensaje final con este bloque exactamente, para que un orquestador pueda analizarlo:

RESULT: done | blocked | needs-split | already-met
TICKET: <id local> / <clave del tracker o "unpublished">
PR: <url o "none">
BRANCH: <rama o "none">
SKIPPED: <límites deliberados o elementos no abordados, o "none">
NOTES: <una o dos líneas: por qué bloqueado, qué dividir, seguimientos, problemas no relacionados encontrados>