inq-roi-simulador-web/methodology/AUTOMATION_STRATEGY.md

# 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**.