Guía de "Bug Fix Cycle"

Esta guía está pensada para entender qué hace el asistente de IA cuando ejecuta este playbook. La idea es que puedas leerla, entender qué pasa en cada paso, y saber qué información tenés que darle al asistente para que el trabajo salga bien.

Nombre técnico interno: en el repositorio este playbook está guardado como bug-tdd-fix.md. "Bug Fix Cycle" es su nombre funcional — el ciclo completo de corregir un bug, desde que se detecta hasta que queda comprobado y documentado que se arregló.

1. ¿Qué es un "playbook"?

Pensalo como una receta de cocina para el asistente de IA. Vos le decís "quiero hacer esto" (por ejemplo, "quiero corregir este bug y dejarlo probado") y el playbook es la receta que el asistente sigue paso a paso, en orden, sin saltarse nada, para que el resultado sea siempre el mismo sin importar quién lo pida.

Cada paso de la receta usa una herramienta puntual (en la jerga técnica se las llama "skills"), algo así como un utensilio de cocina: uno sirve para pelar, otro para cortar, otro para hornear. Vos no necesitás saber cómo funciona cada utensilio por dentro — solo necesitás saber qué ingrediente hay que poner en cada paso (por ejemplo, en qué falla la aplicación, o en qué URL se reproduce) para que el plato final salga bien.

En resumen: un playbook = una guía ordenada de pasos. Una skill = la herramienta puntual que ejecuta cada paso. Interactuás con el playbook — el asistente se encarga de usar la herramienta correcta en cada momento.

2. ¿Qué hace el playbook "Bug Fix Cycle"?

Es el playbook que usás cuando aparece un bug (algo que la aplicación hace mal) y querés que quede corregido y, sobre todo, que quede "atrapado" para siempre por una prueba automática, para que nunca más vuelva a pasar sin que nadie se dé cuenta.

Hoy, cuando alguien reporta un bug, lo habitual es:

Alguien intenta reproducirlo a mano para confirmar que existe.
El developer lo arregla "a ojo", confiando en que entendió bien el problema.
Nadie deja una prueba automática que confirme, de una vez y para siempre, que ese bug específico no vuelve a aparecer en el futuro (lo que se conoce como una "regresión").

Este playbook cambia ese orden: primero se escribe una prueba que demuestra que el bug existe (y que falla, a propósito), después se corrige el bug, y recién ahí se confirma que la prueba ahora pasa. A esta técnica se la llama TDD (a las siglas en inglés no hace falta prestarles atención — lo que importa es la idea: "primero la prueba que falla, después el arreglo, después la prueba que pasa").

Al terminar, el bug queda con:

Evidencia real de que el bug existía (pasos exactos + una captura de pantalla del problema).
Una prueba automática guardada para siempre, que en el futuro va a avisar solo si ese bug vuelve a aparecer.
Confirmación de que el arreglo del developer realmente funcionó.
Confirmación de que arreglar ese bug no rompió ninguna otra parte de la aplicación.
Un reporte que muestra, en la misma página, el "antes" (bug presente) y el "después" (bug corregido) — ideal para cerrar el ticket con evidencia formal.

3. ¿Cuándo tengo que usar este playbook?

Usalo cuando estés frente a alguna de estas situaciones:

Situación	Ejemplo de negocio
Alguien reportó un bug concreto y hace falta confirmarlo y corregirlo con evidencia	Un cliente de TechStore (tienda online) avisa que pudo comprar 5 unidades de un producto que solo tenía 2 en stock, y nadie le mostró un aviso de error.
El ticket exige demostrar que el bug quedó corregido, no solo "confiar" en el developer	El equipo de TechStore tiene una política: ningún bug se cierra sin una prueba que lo compruebe antes y después del fix.
El bug está en una parte de la app que ya tiene pruebas automáticas y se quiere confirmar que arreglarlo no rompió nada más	El módulo de "carrito de compras" de TechStore ya tiene varias pruebas automáticas corriendo; se quiere asegurar que el fix del bug de stock no rompió el cálculo del total.
Se necesita un reporte formal con el detalle de qué fallaba y cómo quedó resuelto	El líder de QA de TechStore pide evidencia documentada para adjuntar al ticket antes de cerrarlo.

¡IMPORTANTE!

Este playbook asume que el proyecto ya está configurado para QA automatizado (es decir, ya existe el archivo qa-stack.yaml que es el resultado de haber ejecutado el playbook New Project Bootstrap). Si TechStore fuera un proyecto totalmente nuevo sin nada de esto configurado, primero hay que correr el playbook "New Project Bootstrap" — este playbook es para el día a día, no para arrancar de cero.
Si lo que hay que probar no es un bug sino un cambio visual o de diseño (por ejemplo, se movió un botón de lugar), no es este playbook — existe uno específico para cambios de interfaz.
Este playbook necesita que un developer esté disponible en algún momento del proceso, porque se detiene a mitad de camino esperando que se aplique el arreglo. No es un proceso 100% desatendido.

4. Ejemplo guía: "TechStore", una tienda online con carrito de compras

Vamos a seguir el mismo caso de negocio que en la guía de "New Project Bootstrap": TechStore, una tienda online de electrónica con carrito de compras.

Esta vez, TechStore ya está en producción y tiene pruebas automáticas funcionando. Un cliente reporta lo siguiente al equipo de soporte:

"Intenté comprar 5 unidades de un mouse que en la web decía que solo quedaban 2 disponibles, y el sistema me dejó agregarlas igual al carrito sin avisarme nada."

El equipo confirma que es un bug real: la regla de negocio dice "el sistema debe mostrar un mensaje de error si el cliente intenta agregar más unidades de las que hay en stock", y esa regla no se está cumpliendo. Ese es exactamente el escenario para el que se usa este playbook.

A lo largo de los pasos siguientes vamos a ver qué le responderías al asistente en cada momento, usando este bug de TechStore como ejemplo.

5. Antes de arrancar: lo que necesitás tener a mano

No hace falta saber programar, pero sí tener a mano estos datos:

Dato	Ejemplo con TechStore
Qué falla exactamente, en palabras simples	"El carrito permite agregar más unidades de un producto que las que hay en stock, sin mostrar ningún error"
Qué regla de negocio se rompe (si existe una historia de usuario o criterio de aceptación de referencia)	"El sistema debe mostrar un mensaje de error si se intenta agregar más unidades que el stock disponible"
En qué ambiente se reproduce el bug	`https://techstore-staging.com`
Un identificador del bug/ticket, si existe	`BUG-42`
Un developer disponible para aplicar el arreglo cuando el playbook llegue a ese punto	El developer del módulo de carrito de TechStore, avisado de antemano

Si no tenés un ticket formal, no es un problema: alcanza con describir el bug en palabras simples, como en el ejemplo de arriba.

6. Cómo arrancar

Antes del Paso 1, contale al asistente el bug a corregir, con la mayor cantidad de detalle posible:

Quiero cubrir con TDD el siguiente bug:
- ID del bug: BUG-42
- Qué falla: el carrito de TechStore permite agregar más unidades de un
  producto que las que hay en stock, sin mostrar ningún error
- Regla que se rompe: "el sistema debe mostrar un mensaje de error si se
  intenta agregar más unidades que el stock disponible"
- Módulo afectado: carrito de compras
- La app está en https://techstore-staging.com
No realices ninguna acción solo utiliza esta información en tu contexto

Con ese contexto, el asistente ya puede recorrer todos los pasos siguientes sin que se lo tengas que repetir cada vez.

7. Paso a paso

Paso 1 — "Entender qué regla de negocio se rompe"

Qué pasa: si existe una historia de usuario o un documento de referencia, el asistente lo lee y busca específicamente la regla (el "criterio de aceptación") que el bug está violando. Si no existe ese documento, simplemente usa la descripción que le diste vos en el paso anterior.

Qué te queda al final de este paso: una frase clara y concreta de cuál es la regla que la aplicación debería cumplir y hoy no cumple. En el caso de TechStore: "el sistema debe mostrar un mensaje de error si se intenta agregar más unidades que el stock disponible".

Si no tenés una historia de usuario a mano, no pasa nada — se puede saltar este paso y darle la regla directamente en el paso siguiente.

Paso 2 — "Reproducir el bug con evidencia real"

Qué pasa: el asistente entra a la aplicación (como lo haría una persona probándola a mano) e intenta reproducir el problema paso por paso, tal como lo describió el cliente. Va guardando cada paso que hace y saca una captura de pantalla en el momento exacto en que se ve el error.

Con TechStore, esto significa que el asistente entra al sitio, busca el mouse con solo 2 unidades en stock, intenta agregar 5 al carrito, y confirma que efectivamente no aparece ningún mensaje de error — dejando registrado ese momento con una captura de pantalla.

Qué te queda al final de este paso:

Los pasos exactos para reproducir el bug (para que cualquiera pueda repetirlo).
Una captura de pantalla del momento en que se ve el problema.
Los datos técnicos del elemento afectado (que el asistente va a usar solo, sin que tengas que intervenir, en el paso siguiente).

Checkpoint: el bug quedó reproducido si hay pasos claros + una captura de pantalla que muestre el problema. Si el asistente no logra reproducirlo, puede ser que el ambiente no sea el correcto o que falte algún dato (por ejemplo, credenciales de acceso).

Paso 3 — "Crear una prueba que 'atrape' el bug"

Qué pasa: con la evidencia del paso anterior, el asistente escribe una prueba automática puntual, específicamente diseñada para detectar este bug. Esa prueba describe cómo debería comportarse la aplicación (mostrando el error de stock), no cómo se comporta hoy (con el bug presente) — por eso, en este momento, la prueba va a fallar a propósito.

Es como armar una alarma que hoy está apagada porque el problema que detecta todavía no se resolvió — en cuanto se resuelva, la alarma se queda callada, y si el problema volviera a aparecer en el futuro, la alarma se dispararía de nuevo sola.

Qué te queda al final de este paso: un archivo de prueba automática nuevo, dedicado exclusivamente a este bug.

Checkpoint 1 — "Confirmar que la alarma suena" (pausa)

Qué pasa: el asistente corre esa prueba nueva una sola vez, para confirmar que efectivamente falla (que "suena la alarma"). Si falla, es la señal correcta: significa que la prueba realmente está detectando el bug.

Resultado	Qué significa	Qué se hace
La prueba falla ❌	Correcto — la prueba efectivamente detecta el bug	Se guarda ese resultado en el historial del proyecto como evidencia formal, y se avanza
La prueba pasa ✅	Algo no cuadra — puede que el bug ya no esté en este ambiente, o que se haya entendido mal la regla de negocio	Revisar con el equipo antes de seguir

Este es un punto de control importante: el resultado de este paso queda guardado como prueba de que el bug existía. Es el "antes" que después se va a comparar con el "después".

[PAUSA] — el developer aplica el arreglo

Qué pasa: acá el playbook se detiene y es el turno del developer para corregir el bug. El asistente entrega la prueba automática del Paso 3 como una consigna clara y ejecutable: "la aplicación tiene que pasar esta prueba".

El developer:

Corre la prueba en su computadora para confirmar que ve el mismo problema.
Corrige el código de la aplicación.
Confirma que ahora la prueba pasa.
Avisa al equipo de QA que el arreglo ya está disponible para verificar (por ejemplo, en el ambiente de staging).

Importante: en este momento nadie más que el developer participa. El asistente espera a que le avisen que el arreglo está listo antes de continuar.

Paso 4 — "Verificar que el arreglo realmente funciona"

Qué pasa: una vez que el developer avisa que aplicó el arreglo, el asistente vuelve a correr la misma prueba del bug (no una nueva) para confirmar que ahora sí pasa.

Con TechStore (la tienda online ficticia que usamos de ejemplo), esto significa que el asistente vuelve a intentar agregar 5 unidades de un producto con solo 2 en stock, y esta vez confirma que sí aparece el mensaje de error esperado.

Checkpoint 2 (pausa):

Resultado	Qué significa	Qué se hace
La prueba pasa, y el asistente no tuvo que "ayudarla" a pasar	El arreglo funciona correctamente ✅	Se avanza al Paso 5
La prueba pasa, pero el asistente tuvo que ajustarla para que pasara	Señal de alerta ⚠️ — puede que el arreglo esté incompleto	Revisar con el developer antes de seguir
La prueba sigue fallando	El arreglo no funcionó ❌	Se devuelve al developer con el detalle completo de por qué sigue fallando

Paso 5 — "Confirmar que no se rompió nada más"

Qué pasa: el asistente corre todas las pruebas automáticas del módulo afectado (no solo la del bug puntual), para confirmar que el arreglo no generó un problema nuevo en otra parte de la aplicación. Si alguna de esas otras pruebas se rompió por el cambio (por ejemplo, porque algo en la pantalla cambió de lugar), el asistente intenta repararla solo.

Con TechStore, esto significa correr todas las pruebas del módulo "carrito de compras" (agregar productos, ver el carrito, calcular el total, aplicar cupones, etc.), no solo la del bug de stock.

Checkpoint 3 (pausa):

Resultado	Qué se hace
Todas las pruebas del módulo quedan en verde	Ya se puede avanzar a mergear el arreglo ✅
Alguna prueba no se pudo reparar sola	Revisar el detalle antes de mergear — puede requerir intervención del developer
La prueba del bug original vuelve a fallar	El arreglo colisionó con otro cambio — hay que revisarlo con el developer antes de seguir

Paso 6 — "Reporte final: antes y después"

Qué pasa: el asistente arma un reporte final que muestra, uno al lado del otro, el resultado de "antes del arreglo" (la prueba fallando, con la captura de pantalla del bug) y "después del arreglo" (la misma prueba pasando), además del resultado de la regresión del módulo completo.

Qué te queda al final de este paso: un documento único que sirve como evidencia formal para cerrar el ticket, mostrando con claridad que el bug existía, que se corrigió, y que no se rompió nada más en el proceso.

8. ¿Qué me queda al finalizar todos los pasos?

Qué obtenés	Para qué te sirve
Evidencia real del bug (pasos + captura de pantalla)	Demuestra que el problema reportado era real y estaba bien identificado
Una prueba automática nueva, dedicada a este bug	Si el bug volviera a aparecer en el futuro, alguien se va a enterar de inmediato, sin que nadie tenga que probarlo a mano de nuevo
Confirmación de que el arreglo del developer funciona	Ya no es "a ojo" — quedó demostrado con una prueba real
Confirmación de que no se rompió nada más en el módulo	El arreglo es seguro de mergear
Un reporte con la comparación antes/después	Evidencia formal para cerrar el ticket o mostrarle al stakeholder

A partir de acá, el bug queda cerrado con evidencia completa, y la prueba que lo detectó pasa a formar parte permanente de la suite de pruebas de TechStore — protegiendo contra que el mismo problema vuelva a aparecer sin que nadie se dé cuenta.

9. Problemas comunes (y qué hacer)

Lo que ves	Por qué puede pasar	Qué hacer
En el Checkpoint 1, la prueba nueva pasa en vez de fallar	El bug no está presente en ese ambiente, o se entendió mal la regla de negocio	Confirmar con el equipo el ambiente correcto y revisar si la regla identificada en el Paso 1 es la correcta
En el Paso 4, la prueba pasa pero el asistente tuvo que "ayudarla"	El arreglo puede estar incompleto	Revisar con el developer si el arreglo cubre por completo el problema reportado
En el Paso 5, otras pruebas del módulo fallan y no se pueden reparar solas	El arreglo cambió algo en la pantalla o en el comportamiento que otras pruebas daban por hecho	Puede requerir intervención del developer — no es necesariamente un error del arreglo
El bug vuelve a fallar después de la regresión del módulo	El arreglo colisionó con otro cambio hecho en paralelo	Volver a coordinar con el developer antes de mergear
El developer modificó sin querer el archivo de la prueba en vez de solo el código de la aplicación	Confusión entre "el archivo de prueba" y "el código a corregir"	El arreglo debe estar solo en el código de la aplicación; la prueba no se toca

10. Resumen visual del flujo

Bug reportado (ej: TechStore permite comprar más stock del disponible)
            │
            ▼
Paso 1 — Entender qué regla de negocio se rompe
            │
            ▼
Paso 2 — Reproducir el bug con evidencia real (pasos + captura)
            │
            ▼
Paso 3 — Crear una prueba que "atrape" el bug
            │
            ▼
Checkpoint 1 — Confirmar que la prueba falla (evidencia del "antes")
            │
            ▼
[PAUSA — el developer aplica el arreglo]
            │
            ▼
Paso 4 — Verificar que el arreglo funciona (la prueba ahora pasa)
            │
            ▼
Paso 5 — Confirmar que no se rompió nada más en el módulo
            │
            ▼
Paso 6 — Reporte final con comparación antes/después
            │
            ▼
Bug cerrado, con evidencia y prueba permanente contra que vuelva a pasar