From 293c225819dc192b1c6d2fdc4d681a86dfa90b27 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20Ben=C3=ADtez?= Date: Sat, 16 May 2026 21:38:43 -0300 Subject: [PATCH] =?UTF-8?q?docs(methodology):=20estrategia=20de=20automati?= =?UTF-8?q?zaci=C3=B3n=20de=20validaci=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Agrega: - AUTOMATION_STRATEGY.md: roadmap de 5 fases desde validación 100% humana hasta pipeline multi-agente - PATTERNS.md: patrón C.5 (validaciones programáticas en prompt) + nota en C.1 sobre evolución a fases superiores - PRINCIPLES.md: extensión del Principio 5 con distinción entre actividades irremplazables vs delegables del humano Decisión: InQ ROI Sprint 1.5 permanece en Fase 1. Evolución a Fase 2 después de Sprint 1.5 con criterios documentados. --- ....gz => methodology-initial-commit-2.tar.gz | Bin methodology/AUTOMATION_STRATEGY.md | 184 ++++++++++++++++++ methodology/PATTERNS.md | 43 ++++ methodology/PRINCIPLES.md | 30 +++ 4 files changed, 257 insertions(+) rename methodology-initial-commit.tar.gz => methodology-initial-commit-2.tar.gz (100%) create mode 100644 methodology/AUTOMATION_STRATEGY.md diff --git a/methodology-initial-commit.tar.gz b/methodology-initial-commit-2.tar.gz similarity index 100% rename from methodology-initial-commit.tar.gz rename to methodology-initial-commit-2.tar.gz diff --git a/methodology/AUTOMATION_STRATEGY.md b/methodology/AUTOMATION_STRATEGY.md new file mode 100644 index 0000000..e65c257 --- /dev/null +++ b/methodology/AUTOMATION_STRATEGY.md @@ -0,0 +1,184 @@ +# 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**. \ No newline at end of file diff --git a/methodology/PATTERNS.md b/methodology/PATTERNS.md index 88d939c..e896ba7 100644 --- a/methodology/PATTERNS.md +++ b/methodology/PATTERNS.md @@ -115,6 +115,11 @@ Si el output de la etapa es un artefacto visible (PDF, screenshot, página rende - Páginas web: dev server en navegador - Documentos: editor que renderice (no solo source) +**Cuándo evolucionar este patrón:** ver methodology/AUTOMATION_STRATEGY.md. +La validación visual humana es Fase 1. Puede complementarse con agentes +auditores (Fase 3) pero NO se reemplaza completamente hasta que el +equipo desarrolle criterio adversarial maduro. + --- ### C.2 Validación programática antes de declarar completado (agente) @@ -163,6 +168,44 @@ Análisis de píxeles del heatmap: verde 36.329px, ámbar 3.889px, rojo 3.713px Text extraction confirma palabras clave: "InQ ROI", "Powered by InQuality", "Payback" ``` +### C.5 Validaciones programáticas explícitas en el prompt +**Estado:** propuesto · **Deriva de:** Principios 2 y 5 + +Cada prompt de etapa incluye una sección **"Validaciones automatizadas mandatorias"** con criterios objetivos verificables por código que el agente debe ejecutar antes de declarar terminada la etapa o usar `present_files`. + +**Por qué:** documenta explícitamente qué se va a auto-validar, hace transferible el conocimiento operativo al equipo, captura el aprendizaje sobre qué problemas son recurrentes y vale la pena chequear automáticamente. + +**Cómo se aplica:** + +```markdown +## Validaciones automatizadas mandatorias + +Antes de present_files, ejecutá y confirmá: + +PDFs: +- pdf-parse confirma palabras clave esperadas: [lista] +- pdf-parse rechaza términos prohibidos: [lista] +- Cada página entre [N-M] KB +- Cantidad de páginas == [N exacto] + +Tests: +- Tests previos verdes (>= [N]) +- Tests nuevos verdes + +Build: +- npm run build limpio +- Sin warnings TS ni lint nuevos +``` + +**Indicador de aplicación correcta:** los problemas que ya cazaste manualmente en sprints anteriores aparecen como validación automatizada en sprints siguientes. Aprendizaje acumulativo. + +**Indicador de violación:** el agente declara etapa terminada y vos cazás el mismo tipo de problema que ya cazaste 3 etapas atrás. Significa que el aprendizaje no se está capturando como validación. + +**Relación con otros patrones:** +- Extiende **C.2** (validación programática) haciéndola explícita en el prompt +- No reemplaza **C.1** (validación visual humana) — son complementarias +- Es Fase 2 del roadmap de `AUTOMATION_STRATEGY.md` + --- ## Categoría D — Estructura del repo diff --git a/methodology/PRINCIPLES.md b/methodology/PRINCIPLES.md index 21b4cff..2a8b2c0 100644 --- a/methodology/PRINCIPLES.md +++ b/methodology/PRINCIPLES.md @@ -71,8 +71,38 @@ Tu trabajo es decidir **qué** se hace, **cuándo** se valida, y **si** lo entre - Si la decisión es repetitiva (formato, nombre, paleta), documentala una vez y referenciala. - Si te volvés "pasamanos" entre dos agentes, frená y revisá el flujo. +**Distinción crítica: actividades irremplazables vs delegables** + +Dentro del rol del humano hay dos tipos de actividad. Confundirlas lleva a automatizar lo que no se debe (perdiendo aprendizaje) o a delegar lo que no se puede (perdiendo calidad). + +### Actividades irremplazables del humano + +Estas NO se automatizan, aunque la tecnología eventualmente lo permita. Su valor depende del juicio humano contextualizado: + +- **Criterio adversarial:** detectar anomalías que no están codificadas como regla. Surge del modelo mental del producto. +- **Calibración contextual:** adecuar decisiones al cliente, sector, cultura, momento del negocio. +- **Decisión arquitectónica:** elegir trade-offs cuando varios caminos son válidos. +- **Evolución del método:** identificar cuándo el método actual ya no sirve y cambiarlo. + +### Actividades delegables a automatización + +Estas SÍ se automatizan, gradualmente, siguiendo el roadmap escalonado de `methodology/AUTOMATION_STRATEGY.md`: + +- Verificación de presencia/ausencia de elementos (texto, colores, archivos) +- Verificación de cumplimiento de reglas explícitas +- Transporte de contexto entre sesiones +- Detección de anomalías estadísticas (tamaños, cantidades, tiempos) +- Validación de regresiones + +**Regla operativa:** automatizá las delegables primero, las irremplazables nunca. Si te encontrás automatizando algo y perdiendo el reflejo de hacerlo manualmente, parar y reconsiderar. + + **Cuándo NO aplica:** las primeras 2-3 veces que aplicás el método, la operación manual es parte del aprendizaje. Después, la operación es señal de fricción que hay que eliminar. +**Documento relacionado:** ver `methodology/AUTOMATION_STRATEGY.md` +para el roadmap escalonado de automatización de validación (5 fases, +desde validación humana 100% hasta pipeline multi-agente). + --- ## Cómo se relacionan los 5 principios