Guía de "Bug Reproduction"

Esta guía explica qué es un playbook de control de calidad (QA) y qué hace exactamente el playbook “Reproducción de bugs”.

1. Conceptos básicos

Antes de arrancar: dejamos algunos de los conceptos básicos que sería bueno entender para este playbook.

1.1 ¿Qué es un playbook?

Es por ejemplo la checklist que sigue un piloto antes de despegar: no improvisa cada vez, sigue una secuencia probada de pasos. Un playbook es esa misma idea aplicada a probar una aplicación: una receta escrita que le indica al modelo de IA, paso a paso, qué hacer usando diferentes elementos/herramientas llamadas "Skills".

¿Qué es una "Skill"?

Una skill es la herramienta puntual que ejecuta cada paso del playbook. Interactúa con el playbook — el asistente se encarga de usar la herramienta correcta en cada momento.

1.2 Bug

Es como seguir una receta de cocina al pie de la letra y que la torta no salga bien. Un bug es una imperfección o deficiencia en un sistema o aplicación que puede surgir como resultado de errores humanos, defectos en los requisitos o en la implementación/desarrollo del software. Los bugs pueden existir en el código sin manifestarse como errores, y su gestión es crucial para mejorar la calidad del software.

1.3 Ticket / historia de usuario

Una historia de usuario representa un requisito de software desde el punto de vista del usuario final o cliente, enfocándose en el valor que aporta y no en los detalles técnicos de implementación. Su objetivo es facilitar la comunicación entre el equipo de desarrollo, testers y stakeholders, asegurando que todos comprendan el propósito de la funcionalidad previamente a ser desarrollada. Por lo general es fundamental que tenga dentro los criterios de aceptación.

1.4 Criterio de aceptación (AC)

Son las condiciones que deben cumplirse para considerar la historia completada. Dentro de un ticket puede haber varias reglas/criterios distintos. Un criterio de aceptación (AC) es una de esas reglas puntuales, EJ.: hablando de un auto (“las luces traseras deben encender”, “el freno de mano sostiene en pendiente”, etc). Si alguno de esos criterios no se cumple se reporta un bug.

1.5 Ambientes: desa, staging/QA, producción y local

Son los lugares donde puede vivir una copia de la aplicación:

Producción: es la función de teatro real, con público pagando entrada: la versión que usan los clientes todos los días.
Staging/QA: es el ensayo general antes del estreno: una copia idéntica, pero sin público real.
Desa: es la sala anterior al ensayo general donde el equipo prepara la entrega para ver que todo vaya a salir bien y no se esté olvidando de nada.
Local: es directamente ensayar en tu propia casa, en tu propia computadora, sin que nadie más lo vea todavía.

Dependiendo de dónde aparece el bug, su severidad indica qué tan urgente es salir a solucionarlo: un bug en producción significa que los clientes reales lo están viendo; un bug en staging es donde se previene y se reporta, para evitar que ese mismo bug llegue a producción cuando la función salga real.

1.6 Reproducir un bug

Es como cuando vas al traumatólogo y te pregunta “¿qué estabas haciendo cuando empezó el dolor?”, y después intenta recrear esas mismas condiciones para confirmar el síntoma en un consultorio, en vez de simplemente creerte de palabra. Reproducir un bug es seguir los mismos pasos exactos que hizo el cliente o QA, hasta lograr que el comportamiento incorrecto vuelva a pasar delante tuyo —recién ahí queda confirmado que el problema es real.

1.7 Evidencia (pasos + capturas)

Es como un parte policial o un reclamo de seguro: no alcanza con decir “se rompió algo”, hace falta contar exactamente qué pasó, en qué orden, y adjuntar fotos. La evidencia de un bug es esa misma idea: los pasos exactos para llegar al problema, más capturas de pantalla que muestren el estado incorrecto/problema descripto. Ejemplo: le robaron una rueda, y se adjunta la foto del auto sin la rueda.

1.8 No reproducible / intermitente

Un bug es “no reproducible” cuando, tras intentarlo siguiendo los pasos, no vuelve a pasar bajo las mismas condiciones. Es “intermitente” cuando pasa, pero no siempre.

1.9 Reporte mínimo

Este playbook, a diferencia de otros, no escribe ni corre pruebas automáticas —solo documenta. Es como la diferencia entre un parte policial y un juicio: el parte no resuelve el caso, pero es lo que hace falta para que el caso arranque. El reporte mínimo es ese documento: datos usados, pasos concretos detallados ordenadamente, evidencia de la falla.

1.10 Ticket de bug (BUG-ID)

Cuando el bug se identifica, para escribir sus pasos y detalle se requiere una herramienta de ticketing donde se abre un ticket con todo el detalle y, al guardar ese ticket, la herramienta nos da un número/link para poder seguirlo y asignarlo a alguien del equipo de desarrollo para su reparación. Generalmente quedan asociados a la historia de usuario que estamos probando, siempre y cuando esté relacionado a eso y no a un bug que encontramos de forma casual navegando la aplicación mientras probábamos la historia de usuario.

2. ¿Qué hace el playbook "Bug Reproduction"?

Es el playbook que usás cuando alguien reportó un comportamiento raro en la aplicación y necesitás confirmarlo y documentarlo con evidencia, antes de mandarlo al equipo de desarrollo.

Pensalo como un parte policial o un reclamo de seguro: no alcanza con decir "se rompió algo" — hace falta contar exactamente qué pasó, en qué orden, y adjuntar pruebas. Este playbook hace eso: repite los mismos pasos que llevan al problema, hasta lograr que el comportamiento incorrecto vuelva a pasar delante del asistente, y documenta todo con capturas de pantalla.

Diferencia clave con otros playbooks: este no genera ni corre pruebas automáticas — su único trabajo es confirmar el bug y documentarlo. Si el bug se confirma y hace falta cubrirlo con pruebas automáticas, eso lo hace un playbook distinto, cada playbook tiene su función (Ej: el camarero no hace el trabajo del cocinero).

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

Usalo cuando:

Alguien reportó un bug y hay que confirmarlo antes de mandarlo a desarrollo.
Hace falta evidencia, no solo la palabra de alguien.
No hay pruebas automáticas para esa parte de la app.

¡IMPORTANTE!

Este playbook no corrige el bug, solo lo confirma y lo documenta.
Necesita que el proyecto ya tenga armado el archivo qa-stack.yaml.

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

Soporte reporta esto:

"Varios clientes dicen que al hacer clic en 'Aplicar cupón' en el carrito, no pasa nada — el descuento nunca se aplica."

Todavía nadie lo vio pasar en persona. Antes de asignárselo a un desarrollador, hace falta confirmarlo: los pasos exactos, y una captura del momento en que falla. Ese es el escenario de este playbook — lo vamos a usar como ejemplo en todos los pasos siguientes.

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

No hace falta saber programar, pero sí tener estos datos a mano — y si no los tenés, acá te decimos dónde conseguirlos:

Dato	Ejemplo con TechStore	De dónde lo sacás
Qué falla	"El botón 'Aplicar cupón' no responde al hacer clic"	Te lo cuenta quien reportó el bug. Preguntale: "mostrame o contame exactamente qué hiciste y qué pasó"
Qué debería pasar en cambio	"Debería aplicar el descuento y actualizar el total"	Preguntale a la misma persona: "¿qué esperabas que pasara?"
URL donde pasa	https://techstore.com/carrito	Te la pasa quien reportó. Si dudás si es producción o pruebas: producción es la dirección de todos los días; los ambientes de prueba suelen tener "staging.", "test." o "preview" en el nombre
Credenciales (solo si hace falta login)	Usuario y contraseña de prueba	Pedíselas al equipo técnico
Historia relacionada (opcional)	Ticket TS-US-14	Te la pasa el desarrollador o tester. Si no hay ticket, no importa — se sigue sin ese dato

6. Cómo arrancar

Antes del Paso 1, contale al asistente el bug que querés reproducir, todo junto en un solo mensaje. Siguiendo el ejemplo de TechStore:

Te paso el contexto del bug (no ejecutes nada) solo guardalo:
- Descripcion del problema: el botón "Aplicar cupón" no responde al hacer clic en el carrito
- Resultado Esperado: debería aplicar el descuento del cupón y actualizar el total a pagar
- URL: https://techstore.com/carrito
- Historia relacionada: user-stories/TS-US-14.md (opcional), puede no haberla (no es lo recomendable) o puede que el proyecto ya sea muy viejo y toda la documentacion de inicio de desarrollo de la aplicacion nunca fue creada porque se fue haciendo de forma mas casera, entonces a veces la definicion esta en el codigo o en el uso del sentido comun de quien esta usando la aplicacion, luego el equipo de IT se ocupara de definir si realmente es un bug o una mejora o un nuevo requerimiento inclusive de algo ya existente sin esa definicion.

El asistente va a usar ese contexto durante todos los pasos siguientes.

Relación con el Paso 1: el contexto que das acá siempre se usa. Si además tenés una historia, el Paso 1 la lee y la complementa (criterio de aceptación exacto, URL, credenciales). Si no tenés historia, este contexto reemplaza al Paso 1: lo salteás y vas directo al Paso 2.

7. Paso a paso

Paso 1 (opcional) — "Leer la historia afectada"

Trigger: /qa-read-user-story <ruta/a/US-ID.md>

Siguiendo el ejemplo de TechStore:

/qa-read-user-story user-stories/TS-US-14.md

Qué pasa: el asistente lee la historia relacionada (si diste una) y extrae de ahí el criterio de aceptación (AC) específico que está fallando — la regla puntual dentro del ticket, no el ticket entero.

Si no tenés historia disponible: salteá este paso directamente y proveé el contexto en el Paso 2 tal como lo diste en "Cómo arrancar" — el asistente documenta que no hay historia asociada.

Cómo saber si salió bien: el asistente te devuelve un texto concreto, algo como: "AC afectado: 'al aplicar un cupón válido, el total debe recalcularse con el descuento aplicado'" — el resto del playbook se enfoca solamente en ese punto.

Paso 2 — "Exploración dirigida al bug"

Trigger: /qa-scripted-execution

Si corriste el Paso 1 (con historia): pegale al asistente el trigger junto con el AC afectado que te devolvió el Paso 1, todo en un solo mensaje:

/qa-scripted-execution
Focalizá en el escenario del AC que falla: "al aplicar un cupón válido, el total debe recalcularse con el descuento aplicado"

Si salteaste el Paso 1 (sin historia): pegale al asistente el trigger junto con la descripción del bug que ya diste en "Cómo arrancar":

/qa-scripted-execution
Explorá y reproducí este bug:
- Qué falla: el botón "Aplicar cupón" no responde al hacer clic en el carrito
- Esperado: debería aplicar el descuento del cupón y actualizar el total a pagar
- La app está en https://techstore.com/carrito

Qué pasa: el asistente entra a TechStore y repite exactamente los pasos que llevarían a reproducir el problema — agrega un producto al carrito, escribe un cupón válido, hace clic en "Aplicar cupón" — documentando qué pasa en cada paso.

Qué evidencia captura:

Evidencia	Descripción
Pasos de reproducción	La secuencia exacta para llegar al bug
Captura del estado incorrecto	Lo que pasa hoy, mal
Captura del estado esperado	Si existe algún camino alternativo que sí funciona
Identificadores técnicos afectados	Para que quien lo arregle sepa dónde mirar
Errores técnicos de fondo	Mensajes internos, si el bug los deja

Cómo saber si salió bien: el bug queda reproducido si el asistente puede listar los pasos exactos, adjuntar al menos una captura del fallo, y confirmar que lo esperado no ocurre.

Si el asistente no logra reproducirlo, eso también es información valiosa. Lo documenta como "no reproducible en \<ambiente> con \<condiciones probadas>" — no se descarta, se deja constancia de qué se intentó.

Paso 3 — "Reporte mínimo"

Trigger: /qa-write-test-report

Lo único que puede faltar es el ID del ticket del bug. Si no lo mencionaste antes, agregalo al pedir el reporte: /qa-write-test-report El ID del ticket es BUG-42. Todo lo demás (hallazgos, AC afectado, URL) el asistente lo toma de la conversación — no hace falta escribir nada más.

Qué pasa: el asistente junta todo lo del Paso 2 en un reporte con fecha y hora, que no sobrescribe reportes anteriores. Este reporte no incluye pruebas automáticas — este playbook no genera ninguna.

Cómo saber si salió bien: el reporte tiene al menos 3 pasos concretos, al menos una captura adjunta, y dice claramente el estado de reproducibilidad: sí, no, o intermitente.

Paso 4 (manual) — "Actualizar el ticket"

Hoy no hay integración automática con Jira ni con ningún otro gestor de tickets — este paso lo hacés vos, fuera del chat:

Abrí el ticket del bug en tu sistema (o creá uno nuevo, con un título corto).
Pegá el contenido del reporte del Paso 3 en el cuerpo del ticket (o adjuntá el archivo si tu sistema lo permite).
Adjuntá las capturas de pantalla generadas en el Paso 2.
Marcá el estado de reproducibilidad y asigná el ticket al equipo de desarrollo.

Si no tenés un gestor de tickets: si el bug se reportó por chat o mail, respondé en ese mismo hilo con el reporte y las capturas. El archivo del reporte igual queda guardado con fecha y hora como registro.

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

Qué obtenés	Para qué te sirve
Los pasos exactos de reproducción	Cualquiera puede repetir el bug sin adivinar
Capturas de pantalla del estado incorrecto	Evidencia visual, no solo una descripción de palabra
El estado de reproducibilidad (sí / no / intermitente)	Define qué hacer a continuación (ver sección 9)
Un reporte con fecha y hora, sin pisar reportes anteriores	Queda un historial versionado de cada intento de reproducción

9. ¿Y después? — Qué hacer según el resultado

Situación	Siguiente acción
Bug confirmado, sin pruebas automáticas para ese módulo	Correr "Regression on Module" sobre el carrito, una vez que el fix esté listo
Bug confirmado, y el arreglo ya está desplegado	Correr "Smoke Test Post Deploy" para verificar que el arreglo funcionó
Bug no reproducible	No se descarta — se documenta igual en el ticket y se escala con el contexto de lo intentado
Bug intermitente	Se marca como tal en el reporte y se agregan las condiciones de cada intento (dispositivo, horario, tipo de conexión)

10. Problemas comunes (y qué hacer)

Lo que ves	Por qué puede pasar	Qué hacer
El asistente no puede acceder al flujo	Hace falta login y no se dieron credenciales	Conseguirlas con el equipo técnico o con quien reportó el bug
El bug no se reproduce en staging	Solo ocurre en producción, con datos reales que staging no tiene	Documentar esa diferencia en el reporte, no forzar la reproducción
Las capturas de pantalla salen en blanco	Problema de renderizado del entorno de pruebas	Confirmar que el ambiente carga bien en un navegador común antes de reintentar
El reporte no menciona el criterio de aceptación (AC) afectado	Se salteó el Paso 1 sin dar contexto a mano	Agregar el AC manualmente al pedir el reporte en el Paso 3

11. Resumen visual del flujo

Bug reportado (ej: "Aplicar cupón" no responde en el carrito de TechStore)
            │
            ▼
Paso 1 (opcional) — Leer la historia afectada    → AC afectado identificado
            │
            ▼
Paso 2 — Exploración dirigida al bug             → pasos + capturas + reproducibilidad
            │
            ▼
Paso 3 — Reporte mínimo                          → reporte con fecha y hora
            │
            ▼
Paso 4 (manual) — Actualizar el ticket real
            │
            ▼
Según el resultado: Regression on Module / Smoke Test / escalar / marcar intermitente