| name | manual-test |
| description | Systematic manual testing with live bug resolution and stakeholder evidence. Use when the user says "manual test", "pruebas manuales", "test plan", "monta el sistema de pruebas manual", "testear la app", or wants to validate features interactively before a demo or release. The user provides screenshots, the agent diagnoses and fixes bugs in real-time.
|
| context | direct |
| allowed-tools | Read, Grep, Glob, Write, Edit, Bash(*), Agent, WebFetch, mcp__supabase__execute_sql, mcp__supabase__list_tables, mcp__supabase__apply_migration |
| triggers | ["manual-test","pruebas manuales","test plan","testing manual","QA manual","stakeholder demo","pre-release testing"] |
/manual-test — Pruebas Manuales Sistemáticas
Sistema de testing manual interactivo: el agente prepara itinerarios, seed data, y guía al usuario paso a paso. Ante bugs, diagnostica y resuelve en el momento. Genera evidencia auditable para stakeholders.
Sub-comandos
| Comando | Acción |
|---|
/manual-test | Genera plan completo desde cero + empieza IT-1 |
/manual-test status | Muestra resumen ejecutivo del progreso |
/manual-test next | Prepara y empieza siguiente itinerario pendiente |
/manual-test seed IT-N | Ejecuta seed data de un itinerario específico |
/manual-test report | Genera informe de evidencia para stakeholders |
/manual-test reset IT-N | Resetea un itinerario para re-testear |
Paso 0 — Detectar contexto del proyecto
Antes de cualquier acción:
- Leer
CLAUDE.md del proyecto para entender stack, arquitectura, BD
- Buscar spec/PRD: revisar si existe SpecBox (
list_us, list_uc) o archivos doc/prd/, doc/spec/
- Identificar BD: buscar config de Supabase, PostgreSQL, Firebase, etc.
- Detectar rutas: leer el router (GoRouter, React Router, etc.) para mapear URLs a features
- Detectar roles de usuario: buscar enum/constantes de roles (rider, sponsor, team_admin, etc.)
Guardar hallazgos en variables internas para los pasos siguientes.
Paso 1 — Generar plan de itinerarios
A partir de los UCs/USs del proyecto, generar itinerarios agrupados por flujo funcional (no por UC individual).
Reglas de agrupación
Principio: Un itinerario = un flujo end-to-end que un usuario real haría.
Agrupar por:
1. Flujos de entrada (auth: registro → verificación → selección de rol)
2. Flujos de onboarding (uno por rol: rider, sponsor, team, etc.)
3. Flujos de feature core (perfil, suscripción, contenido, dashboard)
4. Flujos transversales (i18n, notificaciones, reset password)
5. Flujos de protección (guardian, admin, moderación)
Cada itinerario debe:
- Tener 3-9 pasos (ni muy granular ni muy amplio)
- Cubrir 1-6 UCs relacionados
- Ser independiente (ejecutable sin completar otros IT, excepto auth)
- Tener precondiciones claras (rol, seed data, estado)
Formato del itinerario
| IT-N | Nombre descriptivo | UCs cubiertos | Pasos | Estado |
Para cada itinerario, generar internamente:
- Precondiciones: rol necesario, onboarding completado o no, seed data
- Seed SQL: queries INSERT para poblar la BD con datos de test
- Pasos: tabla con #, descripción, ruta, AC esperado
- Postcondiciones: queries SELECT para verificar estado tras el test
Paso 2 — Crear archivo de evidencia
Crear doc/testing/manual-test-evidence.md usando la plantilla:
# Registro de Pruebas Manuales — {proyecto}
**Proyecto**: {nombre}
**Tester**: {nombre del usuario} (rol)
**Asistido por**: Claude Code (Opus 4.7)
**Fecha inicio**: {fecha}
**Entorno**: localhost ({stack}) + {BD}
---
## Resumen ejecutivo
| Itinerario | UCs | Pasos | Pass | Fail | Blocked | Estado |
|-----------|-----|:-----:|:----:|:----:|:-------:|--------|
{tabla generada en Paso 1}
---
## Bugs encontrados y resueltos durante testing
| # | Bug | Severidad | Commit fix | Estado |
|---|-----|-----------|-----------|--------|
---
{secciones por itinerario — se rellenan conforme se ejecutan}
Paso 3 — Preparar seed data
Para cada itinerario que requiera datos:
- Verificar estructura de BD:
SELECT column_name, data_type FROM information_schema.columns WHERE table_name = '...'
- Verificar CHECK constraints:
SELECT conname, pg_get_constraintdef(oid) FROM pg_constraint WHERE conrelid = '...'::regclass AND contype = 'c'
- Verificar FK constraints: evitar insertar con UUIDs falsos si hay FKs a
auth.users
- Generar SQL de seed con datos realistas y variados (diferentes estados, fechas distribuidas en 6 meses, etc.)
- Guardar seed en
doc/testing/seeds/it-{N}-{nombre}.sql para reproducibilidad
Patrón de seed por tipo de dato
now() - interval 'N months' + interval 'M days'
Paso 4 — Ejecutar itinerario interactivo
Para cada itinerario pendiente:
4.1 — Preparación
- Verificar precondiciones (rol del usuario, onboarding status)
- Ejecutar seed SQL si necesario
- Informar al usuario: "Hot restart y navega a {ruta}. Mándame screenshot."
4.2 — Ejecución paso a paso
Para cada paso del itinerario:
- Indicar al usuario qué hacer: "Rellena X, haz clic en Y, mándame screenshot"
- Analizar screenshot que envía el usuario
- Si PASS: marcar paso, pedir siguiente acción
- Si FAIL/BUG detectado:
a. Leer el error (en pantalla, en logs, en consola)
b. Diagnosticar causa raíz leyendo el código
c. Aplicar fix en el código
d. Verificar que compila (
flutter analyze / npm run lint / etc.)
e. Registrar como BUG-XXX en la tabla de bugs
f. Pedir al usuario que recargue y reintente el paso
4.3 — Cierre del itinerario
- Actualizar tabla de resumen ejecutivo (pass/fail/blocked counts)
- Documentar la sección detallada del itinerario en el evidence file
- Si hay bugs resueltos, guardar en engram memory
Patrones de bugs comunes a buscar proactivamente
| Patrón | Causa típica | Diagnóstico |
|---|
| "No encontrado" en una page autenticada | Router pasa profileId en vez de userId | Verificar qué ID pasa el router vs qué busca el repository |
| Redirect loop tras completar un flujo | profileNotifier no refrescado | Añadir AuthCheckRequested antes de context.go() |
| PostgrestException UUID inválido | Ruta paramétrica (/:id) captura ruta estática (/dashboard) | Mover rutas estáticas ANTES de paramétrizadas |
| Status/type mismatch | Código usa 'completed' pero BD permite solo 'paid' | Verificar CHECK constraints de la tabla |
| Columna no existe (PGRST204) | Código referencia campo que no está en la tabla | Añadir columna vía migración |
| JOIN sin FK (PGRST200) | Query intenta relacionar tablas sin foreign key | Añadir FK o cambiar la query |
Paso 5 — Cambio de rol para testear otros flujos
Cuando un itinerario requiere un rol diferente al actual:
Opción A — Reutilizar usuario existente (más rápido)
UPDATE profiles SET role = '{nuevo_rol}', onboarding_completed = false
WHERE user_id = '{user_id}';
Opción B — Crear usuario nuevo (más realista)
- Solo si la BD permite insertar en
auth.users directamente
- Si hay FK constraints que lo impiden, usar Opción A
Restaurar estado original después
UPDATE profiles SET role = '{rol_original}', onboarding_completed = true
WHERE user_id = '{user_id}';
Paso 6 — Generar informe para stakeholders
Al invocar /manual-test report:
- Leer
doc/testing/manual-test-evidence.md
- Calcular métricas:
- Total itinerarios completados / pendientes
- Total pasos pass / fail / blocked
- Total bugs encontrados / resueltos / abiertos
- Cobertura de UCs testeados vs total
- Generar resumen ejecutivo con formato stakeholder-friendly
- Listar bugs críticos abiertos (si hay)
- Dar veredicto: READY FOR DEMO / BLOQUEADO POR {bugs}
Checklist
Antes de marcar un itinerario como COMPLETADO, verificar:
Referencia rápida
Severidades de bugs
| Severidad | Criterio |
|---|
| Bloqueante | Impide continuar el flujo, crash, data loss |
| Mayor | Funcionalidad rota pero hay workaround |
| Menor | UI issue, texto incorrecto, no bloquea |
| Configuración | Requiere cambio en infra/BD, no en código |
Estructura de archivos generados
doc/testing/
├── manual-test-evidence.md ← Registro vivo principal
├── manual-test-plan.md ← Plan detallado (opcional)
└── seeds/
├── it-01-{nombre}.sql
├── it-02-{nombre}.sql
└── ...
