Saltar a contenido

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.

En resumen

  • Para qué sirve: dejar un bug corregido y "registrado" en una prueba automática que avise si vuelve a aparecer.
  • Cuándo usarlo: cuando alguien reportó un bug concreto y hay que demostrar, con evidencia, que quedó corregido sin romper nada más.
  • Qué necesitás: la descripción del bug, el ambiente donde pasa, el plan de pruebas de la historia, el qa-stack.yaml del proyecto y un developer disponible para aplicar el arreglo.
  • Qué te llevás: evidencia del bug, una prueba automática nueva, la confirmación del arreglo y un reporte con el "antes" y el "después".
  • Pasos: 6 — entender la regla, reproducir el bug, crear la prueba que falla, (pausa para el arreglo), verificar el arreglo, ejecutar la regresión del módulo y armar el reporte antes/después.
¿Qué es un playbook? (si es la primera vez que usás uno)

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.

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.


También existe como planes automáticos

Este ciclo se puede ejecutar sin el asistente, desde el engine de NEO, con dos planes: QA Bug Coverage confirma el bug y deja la prueba en rojo (antes del arreglo), y QA Bug Fix Verification verifica que pasa a verde (después del arreglo).


1. ¿Qué hace este playbook?

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 "registrado" en una serie de tests.

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

  1. Alguien intenta reproducirlo a mano para confirmar que existe.
  2. El developer arregla el bug.
  3. 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.

2. ¿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 en ejecución; 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 de puesta en marcha del proyecto). Si TechStore fuera un proyecto totalmente nuevo sin nada de esto configurado, primero hay que ejecutar ese playbook — este es para el día a día, no para arrancar de cero.
  • Si hay una historia de usuario, este playbook necesita que ya exista su plan de pruebas (el documento con los casos a probar, que por defecto vive en la carpeta test-plans/). La prueba del bug se arma tomando de ese plan el caso que corresponde a la regla rota; sin plan, el asistente no puede generarla y se detiene.
  • 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.

3. 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 puesta en marcha del proyecto: 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.

3.1 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"
La historia de usuario relacionada, si existe: un archivo .md o el link del ticket en Jira o Azure DevOps El archivo de la historia del carrito en user-stories/, o el link del ticket
El plan de pruebas de esa historia El plan del carrito, en la carpeta test-plans/ (por ejemplo, test-plans/<ID-de-la-historia>-test-plan.md)
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.

Playbook original

El playbook general se encuentra en el repositorio NEO-releases.

3.2 Cómo arrancar

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

💬 Prompt para el asistente
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"
- Historia relacionada (si existe): user-stories/<ID-de-la-historia>.md
- 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.


3.3 Paso a paso

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

Skill que se usa: lippia-neo-read-user-story

Qué pasa: si existe una historia de usuario o un documento de referencia (un archivo o el link del ticket en Jira o Azure DevOps), el asistente lo lee y te devuelve la lista de reglas que la historia debe cumplir (los "criterios de aceptación"), junto con la URL de la app y las credenciales de acceso. De esa lista, sos vos quien elige cuál es la regla que el bug está violando — el asistente no la marca por su cuenta. 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".

Checkpoint 0 — Confirmar la regla afectada

Confirmá cuál es el criterio de aceptación que rompe el bug. El resto del playbook gira alrededor de esa regla.

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 de 6 — Reproducir el bug con evidencia real

Skill que se usa: lippia-neo-run-manual-testing

Qué pasa: el asistente entra a la aplicación (como lo haría una persona probándola a mano, siempre navegando la pantalla, nunca "por detrás") 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.

Si hiciste el Paso 1 (con historia): pedile que se enfoque en la regla que confirmaste.

💬 Prompt — Paso 2 con historia
/lippia-neo-run-manual-testing
Focalizá en el escenario del AC: "el sistema debe mostrar un mensaje de error
si se intenta agregar más unidades que el stock disponible"

Con historia, hace falta el plan de pruebas

En este modo el asistente busca el caso dentro del plan de pruebas de la historia (por defecto en test-plans/). Si ese plan no existe, se detiene avisando que "no se encontraron escenarios". En ese caso, usá el modo sin historia de abajo.

Si salteaste el Paso 1 (sin historia): pasale la descripción del bug, incluyendo el ID del bug — el asistente lo usa para nombrar la carpeta donde guarda la evidencia, y sin ese dato no puede arrancar.

💬 Prompt — Paso 2 sin historia
/lippia-neo-run-manual-testing
Explorá libremente y reproducí este bug:
- ID de la ejecución: BUG-42
- Qué falla: el carrito permite agregar más unidades de un producto que las
  que hay en stock, sin mostrar ningún error
- Esperado: mostrar un mensaje de error al superar el stock disponible
- La app está en https://techstore-staging.com

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).

Todo queda guardado en una carpeta propia dentro de execution/ (con el ID de la historia, o con BUG-42 si fue sin historia).

Si el bug es de una API

El asistente siempre reproduce el bug navegando la pantalla de la aplicación. Si el problema está solo en un servicio interno (una API) y no se ve en la pantalla, comparar sus respuestas contra lo esperado queda fuera de este paso.

Checkpoint — ¿El bug quedó reproducido?

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 de 6 — Crear una prueba que "atrape" el bug

Skill que se usa: lippia-neo-generate-test-suite

Qué pasa: con la evidencia del paso anterior, el asistente escribe una prueba automática puntual, específicamente diseñada para detectar este bug. Para eso toma, del plan de pruebas de la historia, solo el caso que corresponde a la regla rota (el resto de los casos los deja de lado) y usa los datos técnicos reales que juntó en el Paso 2. 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. El archivo lleva un comentario al principio que avisa justamente eso: que debe fallar hasta que se corrija el bug.

💬 Prompt para el asistente
/lippia-neo-generate-test-suite
Modo TDD: generá SOLO el test para el AC afectado "el sistema debe mostrar un
mensaje de error si se intenta agregar más unidades que el stock disponible"

Es como armar una alarma que hoy suena 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, dentro de la carpeta de pruebas de la historia (con un nombre del estilo tc-<número>-<descripción-corta>).

Puede aparecer un segundo archivo

Si en el Paso 2 el bug quedó reproducido (el escenario "falló"), el asistente además genera siempre una prueba de regresión aparte para ese escenario, marcada con el ID del bug — salvo que ya exista una con esa marca. No es un error: revisá la lista de archivos generados que te devuelve para saber cuántos quedaron.


Checkpoint 1 — Confirmar que la alarma suena (pausa)

Qué pasa: el asistente ejecuta esa prueba nueva una sola vez, de forma directa (sin ninguna reparación automática), 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. Ese resultado se guarda en un archivo aparte (qa-reports/pre-fix-snapshot.json), que después se usa como el "antes" en el reporte final.

Resultado Qué significa Qué se hace
❌ La prueba falla Correcto — la prueba efectivamente detecta el bug Se guarda la prueba en el historial del proyecto (un "commit" en Git) 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". No se avanza sin guardar la prueba en rojo en el historial del proyecto (el commit): esa es la evidencia formal del bug y forma parte de lo que se exige para cerrar el ticket.


[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:

  1. Ejecuta la prueba en su computadora para confirmar que ve el mismo problema.
  2. Corrige el código de la aplicación.
  3. Confirma que ahora la prueba pasa (sin modificar el archivo de la prueba).
  4. Guarda el arreglo en el historial del proyecto — sin tocar el archivo de la prueba.
  5. Avisa al equipo de QA que el arreglo ya está disponible para verificar (por ejemplo, en el ambiente de staging).

Pausa obligatoria

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 de 6 — Verificar que el arreglo realmente funciona

Skill que se usa: lippia-neo-run-and-heal

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

💬 Prompt para el asistente
/lippia-neo-run-and-heal
Ejecutá solo la prueba del bug BUG-42 con:
- max_iterations: 1
- plateau_detection: false
- run_label: "post-fix"

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.

Un detalle antes de ejecutar

Aunque en este paso no se repara nada si la prueba falla, el asistente igual hace dos chequeos automáticos antes de ejecutarla: completa datos pendientes (valores marcados como TODO) y reemplaza credenciales escritas a mano por las del archivo de configuración. Si toca algo de eso, queda anotado como un "ajuste" a la prueba. Además, si el proyecto usa Lippia en vez de Playwright, no se puede ejecutar una sola prueba: se ejecuta la batería completa.

Checkpoint 2 — ¿El arreglo pasó sin ayuda? (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: para cerrar el bug, la prueba tiene que pasar sin ningún ajuste
La prueba sigue fallando ❌ El arreglo no funcionó Se devuelve al developer con el detalle completo de por qué sigue fallando

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

Skill que se usa: lippia-neo-run-and-heal

Qué pasa: el asistente ejecuta 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 (hasta 3 intentos).

💬 Prompt para el asistente
/lippia-neo-run-and-heal
Ejecutá todos los tests del módulo carrito con:
- max_iterations: 3
- plateau_detection: true
- run_label: "regresion-modulo"

Con TechStore, esto significa ejecutar 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 — ¿El módulo quedó sano? (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 que deja el asistente 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 de 6 — Reporte final: antes y después

Skill que se usa: lippia-neo-write-test-report

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. Esa comparación aparece en una sección propia del reporte, llamada "Diff antes/después".

Para que el reporte pueda decir qué reglas de la historia quedaron cubiertas, el asistente necesita la historia y sus criterios de aceptación del Paso 1. Si no los tiene (por ejemplo, porque salteaste ese paso), la parte de cobertura del reporte queda marcada como "no evaluable" — no es un error, solo significa que no había contra qué compararla.

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. Queda guardado en la carpeta de reportes del proyecto (por defecto test-results/reports/), con un nombre del estilo <ID-de-la-historia>-bug-BUG-42-test-report-<fecha-y-hora>.md.


3.4 ¿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.


4. 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 2 o 3 el asistente se detiene diciendo que no encuentra escenarios o el plan La historia no tiene todavía su plan de pruebas Armar primero el plan de pruebas de la historia, o hacer el Paso 2 en el modo sin historia
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
La prueba del bug no usa los datos técnicos reales de la pantalla En el Paso 2 no se generó el archivo de evidencia completo (solo el documento legible) Volver a ejecutar el Paso 2 y confirmar que quedaron los dos archivos de evidencia
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
La prueba falla en el login Las credenciales de prueba del proyecto (archivo .env.tests) están vacías o incompletas Avisarle a alguien del equipo técnico para que complete los valores reales — nunca se escriben a mano dentro de las pruebas — y repetir el Paso 4 o 5

5. Resumen visual del flujo

flowchart TD
    A([🐞 Bug reportado<br/>ej: TechStore permite comprar<br/>más stock del disponible]) --> B
    B["<b>Paso 1</b> — Entender qué regla<br/>de negocio se rompe"] --> C
    C["<b>Paso 2</b> — Reproducir el bug<br/>con evidencia real"] --> D
    D["<b>Paso 3</b> — Crear una prueba<br/>que atrape el bug"] --> E{¿La prueba falla?}
    E -->|Pasa| F([⚠️ Revisar ambiente<br/>o regla con el equipo])
    E -->|Falla| G["<b>Checkpoint 1</b> — Guardar la prueba<br/>en rojo como evidencia"]
    G --> H["<b>Pausa</b> — El developer<br/>aplica el arreglo"]
    H --> I["<b>Paso 4</b> — Verificar que<br/>el arreglo funciona"]
    I --> J{¿Pasa sin ayuda?}
    J -->|No| H
    J -->|Sí| K["<b>Paso 5</b> — Confirmar que no se<br/>rompió nada más en el módulo"]
    K --> L{¿Módulo en verde?}
    L -->|No| H
    L -->|Sí| M["<b>Paso 6</b> — Reporte final<br/>con antes y después"]
    M --> N([✅ Bug cerrado, con evidencia<br/>y prueba permanente])