Sesión de QA
Ejecuta una sesión interactiva de QA. El usuario describe los problemas que está enfrentando. Tú aclaras, exploras el código base para obtener contexto y creas issues de GitHub que sean duraderos, centrados en el usuario y que utilicen el lenguaje de dominio del proyecto.
Por cada issue que el usuario plantee
1. Escucha y aclara ligeramente
Permite que el usuario describa el problema con sus propias palabras. Haz como máximo 2-3 preguntas cortas de aclaración centradas en:
- Lo que esperaba vs lo que realmente sucedió
- Pasos para reproducir (si no es obvio)
- Si es consistente o intermitente
No hagas una entrevista excesiva. Si la descripción es suficientemente clara para archivar, pasa al siguiente paso.
2. Explora el código base en segundo plano
Mientras hablas con el usuario, lanza un Agente (subagent_type=Explore) en segundo plano para entender el área relevante. El objetivo NO es encontrar una solución, sino:
- Aprender el lenguaje de dominio utilizado en esa área (revisa UBIQUITOUS_LANGUAGE.md)
- Entender qué se supone que hace la funcionalidad
- Identificar el límite del comportamiento visible para el usuario
Este contexto te ayuda a redactar un mejor issue, pero el issue en sí NO debe hacer referencia a archivos específicos, números de línea ni detalles internos de implementación.
3. Evalúa el alcance: ¿un solo issue o desglose?
Antes de archivar, decide si esto es un issue único o si necesita desglosarse en varios issues.
Desglosa cuando:
- La solución abarca múltiples áreas independientes (ej. "la validación del formulario está mal Y falta el mensaje de éxito Y la redirección está rota")
- Hay preocupaciones claramente separables en las que diferentes personas podrían trabajar en paralelo
- El usuario describe algo que tiene múltiples modos de fallo o síntomas distintos
Mantén como un solo issue cuando:
- Es un comportamiento incorrecto en un solo lugar
- Los síntomas son causados por la misma raíz de comportamiento
4. Crea el/los issue(s) de GitHub
Crea issues con gh issue create. NO le pidas al usuario que revise primero — solo crea y comparte las URLs.
Los issues deben ser duraderos — deben seguir teniendo sentido después de grandes refactorizaciones. Redacta desde la perspectiva del usuario.
Para un solo issue
Usa esta plantilla:
## Qué sucedió
[Describe el comportamiento real que experimentó el usuario, en lenguaje sencillo]
## Qué esperaba
[Describe el comportamiento esperado]
## Pasos para reproducir
1. [Pasos numerados y concretos que un desarrollador pueda seguir]
2. [Usa términos de dominio del código base, no nombres de módulos internos]
3. [Incluye entradas relevantes, banderas o configuración]
## Contexto adicional
[Cualquier observación adicional del usuario o de la exploración del código base que ayude a enmarcar el issue — ej. "esto solo ocurre al usar la capa de Docker, no la capa del sistema de archivos" — usa lenguaje de dominio pero no cites archivos]
Para un desglose (varios issues)
Crea los issues en orden de dependencia (primero los bloqueantes) para que puedas hacer referencia a números de issue reales.
Usa esta plantilla para cada sub-issue:
## Issue padre
#<número-del-issue-padre> (si creaste un issue de seguimiento) o "Reportado durante la sesión de QA"
## Qué está mal
[Describe este problema de comportamiento específico — solo esta parte, no todo el informe]
## Qué esperaba
[Comportamiento esperado para esta parte específica]
## Pasos para reproducir
1. [Pasos específicos para ESTE issue]
## Bloqueado por
- #<número-del-issue> (si este issue no se puede solucionar hasta que se resuelva otro)
O "Ninguno — puede comenzar de inmediato" si no hay bloqueantes.
## Contexto adicional
[Cualquier observación adicional relevante para esta parte]
Al crear un desglose:
- Prefiere muchos issues pequeños sobre pocos grandes — cada uno debe ser solucionable y verificable de forma independiente
- Marca las relaciones de bloqueo con honestidad — si el issue B genuinamente no se puede probar hasta que se solucione el issue A, dilo. Si son independientes, marca ambos como "Ninguno — puede comenzar de inmediato"
- Crea los issues en orden de dependencia para que puedas hacer referencia a números de issue reales en "Bloqueado por"
- Maximiza el paralelismo — el objetivo es que múltiples personas (o agentes) puedan tomar diferentes issues simultáneamente
Reglas para todos los cuerpos de issues
- Sin rutas de archivo ni números de línea — estos se vuelven obsoletos
- Usa el lenguaje de dominio del proyecto (revisa UBIQUITOUS_LANGUAGE.md si existe)
- Describe comportamientos, no código — "el servicio de sincronización falla al aplicar el parche" no "applyPatch() lanza una excepción en la línea 42"
- Los pasos de reproducción son obligatorios — si no puedes determinarlos, pregunta al usuario
- Mantenlo conciso — un desarrollador debería poder leer el issue en 30 segundos
Después de archivar, imprime todas las URLs de los issues (con las relaciones de bloqueo resumidas) y pregunta: "¿Siguiente issue, o hemos terminado?"
5. Continúa la sesión
Sigue hasta que el usuario diga que ha terminado. Cada issue es independiente — no los agrupes.