Validacion Visual

Validación visual — Probar tu app como humano, no como compilador

"Que el código compile y los tests pasen NO significa que la feature funciona. Funciona cuando alguien la usa de punta a punta y no encuentra bugs."

Por qué existe esta skill (una historia real)

Un agente cerró una feature con una validación "verde": 10 de 10 pruebas pasaban. El dueño del proyecto entró a mano, con su sesión real, y en 5 minutos cazó 3 bugs que iban directo a producción:

1. Un filtro que no filtraba (caché del framework servía datos viejos).
2. Una configuración que se guardaba bien… pero nunca se aplicaba.
3. Una fecha que mostraba el día anterior (error de zona horaria).

¿Por qué el agente no los vio? Porque su "validación" era entrar sin sesión, ver que redirigía al login, y declarar éxito. Eso se llama smoke validation y es la mentira más cómoda del desarrollo con agentes. Esta skill existe para prohibirla.

Los 2 niveles de profundidad

Nivel 1 — Ligera (default): alcance + halo de regresión

Prueba lo que se construyó o modificó + el halo de regresión: los otros flujos de la app que comparten archivos o componentes con lo tocado. Ahí viven las regresiones invisibles.

Cómo detectar el halo: por cada archivo modificado, busca quién lo consume:

git diff master --name-only          # qué se tocó
grep -r "from.*lib/motor" src/       # quién importa lo tocado
grep -r "import.*MiComponente" src/  # dónde se renderiza el componente compartido

Cada consumidor aporta al menos UN flujo a probar. Duración típica: 15-45 minutos.

Nivel 2 — Exhaustiva (solo si el usuario la pide)

Cada botón, cada filtro y sus combinaciones, cada pestaña, cada rol, móvil (375px) y escritorio, modo claro y oscuro, casos extremos (sin datos, con muchos datos, valores límite). Para hitos: entregar a un cliente, abrir al público, cambio mayor en un motor crítico. Duración típica: 1-3 horas.

El agente NUNCA sube a Nivel 2 por su cuenta — consumiría tiempo y cuota del usuario sin que lo pidiera. El default es Nivel 1.

El flujo

Paso 1 — Mapear el alcance y proponer el plan

Lista lo que se va a probar (alcance directo + halo) y muéstralo antes de ejecutar. Si el alcance es obvio y chico, procede directo. Si el usuario invocó la skill sin decir qué validar, pregunta el alcance — nunca lo asumas.

Paso 2 — Sesión real (si la app tiene login)

Una validación sin sesión no vale. Si la app usa Supabase Auth, el patrón limpio es:

1. Un script local de Node lee la service_role key del .env.local y genera un magic link de administrador (POST /auth/v1/admin/generate_link con { type: 'magiclink', email: '<correo del admin del proyecto>' }). El script imprime SOLO el link — la key jamás se imprime ni entra al contexto del agente.
2. Un endpoint dev TEMPORAL (/api/public/dev-magic-session) recibe los tokens del link y crea la sesión con supabase.auth.setSession(...). Restringido a NODE_ENV !== 'production'.
3. Playwright navega el link → la sesión queda activa → se verifica entrando a una página protegida.
4. El endpoint temporal SE BORRA al terminar la corrida. Se crea, se usa, se elimina. Cero residuos en el repo.

Si la app no tiene login: salta este paso, mismo rigor en el resto.

Paso 3 — Ejecutar el plan con navegador real

Por cada item: navegar → capturar pantalla → ejecutar las acciones como usuario (clics, formularios, flujos completos de varios pasos) → verificar el comportamiento esperado. Screenshots en una carpeta .qa-reports/ (agrégala al .gitignore).

Paso 4 — Bucle de bug-arreglo-revalidación (la regla de oro)

La skill NO termina mientras se sigan encontrando bugs.

1. Bug detectado → reportarlo claro (qué se esperaba, qué pasó, captura).
2. Diagnosticar la causa raíz (no parchar el síntoma).
3. Arreglar + typecheck/lint de lo afectado.
4. Re-validar el flujo completo desde el inicio del paso afectado.
5. ¿El fix expuso otro bug? Vuelve al 1.

Pausa y pregunta en vez de arreglar a la brava cuando: el bug exige una decisión de arquitectura, toca datos reales de producción, o se sale del alcance acordado.

Paso 5 — Limpieza OBLIGATORIA

La base de datos queda IDÉNTICA al estado previo: todo registro de prueba se borra, toda configuración tocada se restaura, el endpoint dev temporal se elimina, el navegador se cierra. Dejar basura de QA en la base del usuario es un bug de la skill.

Paso 6 — Reporte y autorización

• Nivel 1: resumen corto — pasos validados, bugs cazados y resueltos, base limpia.
• Nivel 2: reporte commiteable (tabla de pasos con resultado y captura + detalle de cada bug: síntoma, causa raíz, fix, re-validación + limpieza ejecutada).
• En ambos: el push/deploy final SIEMPRE lo autoriza el usuario. La skill nunca publica sola.

Anti-patrones (prohibidos)

• Smoke validation: entrar sin sesión, ver el redirect al login y declarar éxito.
• Solo el happy path: los bugs viven en el halo de regresión y los casos límite.
• Saltarse el halo "porque solo se tocaron 2 botones".
• Subir a exhaustivo sin que el usuario lo pida (su cuota, su decisión).
• "Encontré el bug pero estaba difícil": si está en alcance, se arregla; si no, se reporta — nunca se ignora.
• Dejar datos de prueba en la base.
• Publicar solo porque el QA salió verde sin autorización del usuario.
• Imprimir llaves o secretos en el chat, en logs o en reportes.