Sesión de QA
Ejecuta una sesión interactiva de QA. El usuario describe los problemas que está encontrando. Tú aclaras, exploras el código base para obtener contexto y creas issues en GitHub que sean duraderos, centrados en el usuario y que utilicen el lenguaje de dominio del proyecto.
Por cada issue que el usuario plantea
1. Escucha y aclara ligeramente
Deja que el usuario describa el problema con sus propias palabras. Haz como máximo 2-3 preguntas cortas de aclaración centradas en:
- Qué esperaba vs qué ocurrió realmente
- Pasos para reproducir (si no son obvios)
- Si es consistente o intermitente
No entrevistes en exceso. Si la descripción es lo suficientemente clara para crear el issue, continúa.
2. Explora el código base en segundo plano
Mientras hablas con el usuario, inicia un Agente (subagent_type=Explore) en segundo plano para comprender 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 escribir un mejor issue, pero el issue en sí NO debe hacer referencia a archivos específicos, números de línea o detalles internos de implementación.
3. Evalúa el alcance: ¿issue único o desglose?
Antes de crear el issue, decide si se trata de un issue único o si es necesario desglosarlo en varios issues.
Desglosa cuando:
- La solución abarca múltiples áreas independientes (por ejemplo, "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 o síntomas de fallo distintos
Mantén como un solo issue cuando:
- Es un comportamiento incorrecto en un solo lugar
- Todos los síntomas son causados por el mismo comportamiento raíz
4. Crea el/los issue(s) de GitHub
Crea los issues con gh issue create. NO le pidas al usuario que revise primero — simplemente crea y comparte las URLs.
Los issues deben ser duraderos — deben tener sentido incluso después de refactorizaciones importantes. Escribe desde la perspectiva del usuario.
Para un issue único
Usa esta plantilla:
## Qué ocurrió
[Describe el comportamiento real que experimentó el usuario, en lenguaje sencillo]
## Qué esperaba
[Describe el comportamiento esperado]
## Pasos para reproducir
1. [Pasos concretos y numerados 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 — por ejemplo, "esto solo ocurre al usar la capa Docker, no la capa de sistema de archivos" — usa lenguaje de dominio pero no cites archivos]
Para un desglose (varios issues)
Crea los issues en orden de dependencia (los bloqueantes primero) 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 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-de-issue> (si este issue no se puede solucionar hasta que se resuelva otro)
O "Ninguno — se puede empezar de inmediato" si no hay bloqueantes.
## Contexto adicional
[Cualquier observación adicional relevante para esta parte]
Al crear un desglose:
- Prefiere muchos issues delgados sobre pocos gruesos — cada uno debe ser independientemente solucionable y verificable
- Marca las relaciones de bloqueo honestamente — si el issue B realmente no se puede probar hasta que el issue A esté solucionado, dilo. Si son independientes, marca ambos como "Ninguno — se puede empezar de inmediato"
- Crea 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 varias personas (o agentes) puedan tomar diferentes issues simultáneamente
Reglas para todos los cuerpos de issue
- Sin rutas de archivo ni números de línea — estos quedan 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 excepción en la línea 42"
- Los pasos de reproducción son obligatorios — si no puedes determinarlos, pregúntale al usuario
- Sé conciso — un desarrollador debería poder leer el issue en 30 segundos
Después de crear, 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.