# Estrategia de automatización de validación > Documento de decisión sobre **qué validaciones automatizar y cuándo**. La automatización prematura de la validación humana destruye el aprendizaje del equipo. La automatización tardía deja al humano como cuello de botella. --- ## Principio rector **El humano valida criterio y contexto. Los agentes y scripts validan facts y reglas.** Este principio se deriva de extender el Principio 5 (humano como director) con la observación de que existen actividades del humano que son **irremplazables** y otras que son **delegables**. ### Actividades del humano irremplazables - **Criterio adversarial:** detectar anomalías sutiles que no están codificadas como regla. Ejemplo: "este PDF pesa 36 KB con 4 páginas, eso es muy poco para el contenido que diseñé". No es lista de chequeo, es modelo mental del producto. - **Calibración contextual:** "¿esto va a funcionar con un cliente de banca corporativa de InQuality?" Implica conocer al cliente, al sector, al contexto cultural. - **Decisión arquitectónica:** cuándo cambiar el método mismo, cuándo aceptar un riesgo, cuándo postergar. - **Calibración del propio método:** detectar cuándo el método actual ya no sirve y necesita evolución. ### Actividades del humano delegables - Verificación de presencia/ausencia de elementos (texto, colores, archivos) - Verificación de cumplimiento de reglas explícitas (marca, paleta, accesibilidad) - Transporte de contexto entre sesiones - Formateo y estructuración de prompts/reportes - Detección de anomalías estadísticas (tamaños, cantidades, tiempos) - Validación de regresiones (tests previos siguen verdes) **La automatización debe atacar las delegables primero, nunca las irremplazables.** --- ## Roadmap escalonado de automatización ### Fase 1 — Validación humana al final (estado actual recomendado) **Cuándo:** durante los primeros 1-2 proyectos completos aplicando el método. Mientras el equipo aprende. **Qué se hace:** el humano abre cada artefacto importante con sus ojos antes del OK. No hay agentes evaluadores. Las validaciones programáticas existen pero son aditivas, no sustitutivas. **Qué se gana:** el equipo desarrolla el reflejo adversarial. Aprende qué es "raro pero técnicamente correcto". Construye modelo mental del producto. **Qué se pierde:** velocidad. El humano es el cuello de botella explícito. **Cuándo salir de esta fase:** cuando al menos 2 miembros del equipo cazan independientemente al menos 3 anomalías sutiles cada uno (no obvias, no en checklist) en proyectos reales. --- ### Fase 2 — Validaciones programáticas explícitas en prompts **Cuándo:** después de Fase 1 estabilizada. Idealmente Sprint 2 o 3 de un proyecto en evolución. **Qué se hace:** cada `ETAPA_X_PROMPT.md` incluye sección "Validaciones automatizadas mandatorias" con criterios objetivos que el agente debe ejecutar antes de declarar terminada la etapa. **Ejemplo de validaciones automatizadas en un prompt:** ```markdown ## Validaciones automatizadas mandatorias (ejecutar antes de present_files) PDFs generados deben cumplir: - pdf-parse confirma palabras clave: ["InQ ROI", "Powered by InQuality"] - pdf-parse rechaza términos prohibidos: ["Process Cost Platform"] - Tamaño de cada página entre 15-80 KB - Heatmap embebido tiene distribución de colores (verde + ámbar + rojo) - Cantidad de páginas = 4 exacto - Tests verdes >= 455 - Build sin warnings nuevos Si CUALQUIER validación falla, NO uses present_files. Reportá el fallo y esperá instrucciones. ``` **Qué se gana:** los problemas obvios se cazan automáticamente. El humano solo ve outputs que ya pasaron los filtros básicos. **Qué se pierde:** el humano debe mantener actualizadas las validaciones cuando el producto evoluciona. **Cuándo salir de esta fase:** cuando el conjunto de validaciones se vuelve repetitivo entre prompts (señal de que vale la pena modularizar). --- ### Fase 3 — Agente revisor especializado (uno solo) **Cuándo:** después de Fase 2 estabilizada. Cuando el equipo ya internalizó el método y las validaciones programáticas son rutina. **Qué se hace:** introducir UN agente especializado que ejecuta una verificación específica. **No varios al mismo tiempo.** El primer agente revisor más útil suele ser el de **marca y consistencia**. **Ejemplo de prompt del Agente Auditor de Marca:** ``` Sos el Auditor de Marca de InQuality. Te paso un artefacto (PDF, screenshot, documento). Tu única tarea es verificar reglas de marca: 1. "InQ" se escribe siempre I-n-Q (I mayúscula, n minúscula, Q mayúscula). Cualquier variante (INQ, Inq, inq, inQ) es BUG. 2. "Powered by InQuality" presente en footer de PDFs. 3. Color naranja InQ (#F59845) predominante en elementos de marca. 4. NO aparecen colores de CONCILIA (#572FA2 morado, #CB1889 magenta). 5. NO aparece el nombre técnico "Process Cost Platform" en ningún lado. 6. Tipografía consistente con sistema de diseño (sans-serif, sin serif). Para cada criterio: PASS / FAIL con cita textual de lo encontrado. Si HAY FAIL, devolvé al implementador con instrucciones específicas. NO declares aprobado hasta que todos PASS. ``` **Cómo se ejecuta concretamente:** - El Implementador (Claude Code) termina su trabajo y produce un PDF - Se invoca al Auditor de Marca (sesión separada de Claude o API call) - El Auditor recibe el PDF como input visual y el prompt de auditoría - Si hay fails, vuelve al Implementador automáticamente **Qué se gana:** verificación consistente de reglas no negociables. Captura errores que el humano puede dejar pasar por fatiga. **Qué se pierde:** complejidad operativa. Hay que coordinar dos agentes. El humano debe mantener actualizados los criterios del auditor. **Cuándo salir de esta fase:** cuando el agente revisor demuestra captura confiable de los errores que estaba diseñado para capturar, durante al menos 1 sprint completo sin falsos negativos importantes. --- ### Fase 4 — Múltiples agentes revisores **Cuándo:** solo después de Fase 3 validada en producción. **Qué se hace:** agregar más agentes revisores especializados. Posibles agentes adicionales: - **Auditor de Accesibilidad:** WCAG, contrast ratios, semantic HTML - **Auditor de Performance:** bundle size, lighthouse score, tamaño de assets - **Auditor de Seguridad:** secrets en código, dependencias vulnerables, exposición de PII - **Auditor de Consistencia:** que el código nuevo no rompa convenciones existentes **Reglas críticas de esta fase:** 1. Agregar un agente a la vez, validar 1 sprint, antes de agregar el siguiente 2. Cada agente tiene un rol acotado y único — si solapan, hay que decidir qué hace cada uno 3. Cuando dos agentes discrepan, **el humano decide**, no se inventa lógica de "voto mayoritario" **Qué se pierde:** mantener N agentes es N veces el costo de mantener uno. Si los criterios cambian, hay que actualizarlos en cada agente. --- ### Fase 5 — Pipeline multi-agente completo **Cuándo:** post-estabilización del producto. Cuando hay >5 proyectos aplicando el método. **Qué se hace:** orquestación formal con frameworks como LangGraph, AutoGen, o Claude Agent SDK. El humano interviene solo cuando todos los agentes fallan o cuando aparece algo nuevo. **Cuando vale la pena:** equipos de 10+ personas, productos en producción estables, donde el costo de la complejidad se amortiza con velocidad. **Cuando NO vale la pena:** equipos chicos, productos en evolución activa, métodos aún en aprendizaje. La sofisticación se vuelve fricción. --- ## Antes de pasar a la siguiente fase: criterios Para saber cuándo subir de fase, verificar 3 condiciones: 1. **La fase actual está estable:** los outputs son consistentes, el equipo no se sorprende negativamente 2. **El cuello de botella es la validación, no otra cosa:** si tu cuello es definición de producto, automatizar validación no ayuda 3. **El equipo internalizó la fase actual:** todos pueden aplicarla sin tu intervención Si las 3 condiciones se cumplen, considerá subir. Si no, quedate. --- ## Anti-patrón explícito: automatización prematura **Comportamiento:** saltarse fases. Por ejemplo, ir directo a Fase 4 sin pasar por 1-2-3. **Daño concreto:** - El equipo nunca desarrolla criterio adversarial — depende de los agentes - Cuando algo falla, nadie sabe diagnosticar porque nunca lo hicieron a mano - Los agentes consumen tokens validando cosas obvias que un humano detectaría en 3 segundos - La complejidad de mantenimiento supera el valor producido **Cómo detectarlo:** si tu primera intuición ante un problema de validación es "agreguemos un agente que lo detecte", probablemente estás en este anti-patrón. Primero preguntá: ¿esto se resuelve con un script de 20 líneas? ¿Con una regla en CLAUDE.md? ¿Con un patrón documentado? **Cómo evitarlo:** seguir el roadmap escalonado. No saltar fases. --- ## Reflexión final La automatización de la validación es **un medio, no un fin**. El fin es que el humano dedique tiempo a lo irremplazable (criterio, contexto, decisión arquitectónica) y delegue lo delegable. Si automatizar te quita tiempo de pensar en producto, **no lo estás haciendo bien**. Si automatizar te libera para pensar en producto, **estás escalando correctamente**.