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

Principios fundamentales

Los 5 principios que sostienen todo el método. Si tu equipo solo recuerda esto, ya tiene 80% del valor. Los patrones son aplicaciones derivadas.

---

1. La especificación precede al código

Antes de pedirle a un agente que genere código, la especificación tiene que estar escrita, versionada y validada. No hay excepciones.

Por qué: un agente sin especificación genera código que parece razonable pero no resuelve el problema que vos tenés. Termina rápido, queda mal, y descubrís el desfase 3 días después cuando es caro arreglarlo.

Cómo se aplica: todo sprint arranca con un brief versionado en sprints/sprint-N/BRIEF.md. Todo cambio importante dentro de un sprint arranca con un mockup o ADR. Todo tarea agéntica arranca con un prompt en archivo, no improvisado en chat.

Cuándo NO aplica: experimentación pura sin entregable. Si estás explorando si una librería sirve, podés hacer prompts libres. Pero el output de esa experimentación nunca va directo a producción.

---

2. La validación humana es ojo, no test

Los tests verdes no equivalen a etapa terminada. El humano abre el artefacto final con sus ojos antes de declarar completado.

Por qué: los agentes producen outputs que técnicamente cumplen los criterios programáticos pero pierden el contexto del producto. Tests verdes garantizan que el código no falla. Validación visual garantiza que el output es presentable.

Cómo se aplica: si el output es un archivo visible (PDF, screenshot, página web, documento), el humano lo abre. Si el output es código, el humano lo lee al menos en diagonal. Si el output es comportamiento (un endpoint que responde algo), el humano lo ejecuta manualmente al menos una vez antes del merge.

Cuándo NO aplica: outputs puramente internos (helpers, refactors estructurales) que se validan exclusivamente por tests. Pero estos casos son minoría.

---

3. La auditoría es adversarial, no confirmatoria

Cuando revisás el output de un agente, buscá lo que está mal, no lo que está bien. Confirmar es fácil; el agente ya viene optimizado para producir cosas que parecen correctas. Tu valor está en detectar lo que el agente racionalizó. Y esto se aplica tanto al output del agente como a tu propia auditoría. Cuando descubrís que algo se te pasó, no es fallo personal — es señal de que la lista de verificación necesita actualizarse.

Por qué: los agentes tienen un sesgo hacia reportar éxito. "Tests verdes, build limpio, etapa completada" suena bien pero puede ocultar que el archivo generado no es el correcto, que la métrica no cuadra con los inputs, o que un detalle crítico se omitió silenciosamente.

Cómo se aplica: cuando recibís un reporte de agente, hacé tres preguntas antes de aprobar:

1. ¿Los números que reportó cuadran si los recalculo a mano o pido detalle?
2. ¿El artefacto entregado es el que pedí o uno parecido?
3. ¿Lo que no menciona el reporte podría ser relevante?

El auditor también debe ser auditado

La auditoría adversarial aplica al agente que produce el artefacto, pero también al humano (o agente delegado) que audita. Los auditores son falibles. Cuando un cambio se descubre tiempo después de haber sido revisado, el caso vale la pena documentarlo — no para culpar al auditor, sino para refinar la lista de cosas a verificar en futuras auditorías.

Caso real (Sprint 1.5 InQ ROI):

En Etapa 7 del sprint, el agente reescribió fórmulas matemáticas de la nota metodológica del PDF ROI a ASCII puro (Σ → "SUM", × → "x"). El cambio no fue mencionado explícitamente en el reporte. El auditor (humano + asesor) validó el PDF visualmente y aprobó la etapa.

Dos etapas después, al auditar Etapa 8, se descubrió que la misma reescritura se había hecho en los otros PDFs, lo cual reveló que el cambio en Etapa 7 también había pasado sin detección.

¿Por qué pasó?

• El auditor revisó la nota metodológica buscando "caracteres Unicode rotos" (£ donde debería haber Σ). Confirmó que seguían rotos en algunos lugares. Asumió que el resto seguía como Etapa 5.
• No verificó el texto exacto, línea por línea, contra una versión previa. Asumió continuidad.
• El cambio era una "no presencia de un problema esperado", no una "presencia de algo nuevo". Auditar la ausencia es más difícil que auditar la presencia.

Aprendizaje operativo:

• Verificar texto exacto contra versión previa cuando se audita un artefacto que ya fue revisado en etapas anteriores. El reporte del agente puede omitir cambios que el auditor no detecta sin comparación directa.
• Cuando un problema esperado deja de aparecer, eso también es un cambio que requiere explicación. Si una etapa "arregla" algo no agendado para arreglar, es señal de adelanto silencioso (ver Anti-Patrón AP.8).
• La auditoría tiene mejor poder de detección al inicio de un artefacto que en revisiones repetidas. Cuando se audita por segunda o tercera vez, el reflejo es comparar contra la versión anterior, no contra el original. Eso puede dejar pasar cambios incrementales.

Implicancia para futuros auditores (incluyendo miembros del equipo):

• Mantener una lista de verificación explícita por tipo de artefacto, no confiar en memoria
• Cuando algo "se ve igual", verificar línea por línea al menos una sección
• Si un reporte parece más limpio de lo esperado, sospechar adelanto silencioso

Esta es la diferencia entre auditoría adversarial real y auditoría adversarial declarativa. Decir "audité adversarialmente" no equivale a haber buscado activamente lo que el agente podría haber cambiado sin reportar.

Cuándo NO aplica: tareas rutinarias de bajo riesgo donde el costo de auditar supera el costo de un error. Pero estas son menos de las que parecen.

---

4. Las decisiones se registran como contratos

Toda decisión arquitectónica, de marca, o de proceso se documenta en el lugar correcto explícitamente, no en la memoria de quien decidió. Cuando aparece de nuevo, no se re-debate.

Por qué: las decisiones no registradas se erosionan. Un agente vuelve a preguntar lo mismo en la siguiente sesión, un miembro del equipo asume distinto, vos mismo en 2 semanas no recordás por qué eligieron X. El costo de re-debatir es alto y los outputs quedan inconsistentes.

Cómo se aplica:

• Decisiones de producto → CLAUDE.md (reglas no negociables) o ARCHITECTURE.md (ADRs)
• Decisiones de método → methodology/PATTERNS.md
• Decisiones de etapa → "DECISIONES YA TOMADAS" en el prompt de la siguiente etapa
• Decisiones de marca → DESIGN_SYSTEM.md o BRAND_GUIDE.md

Cuándo NO aplica: decisiones reversibles sin costo. Si elegís un nombre de variable, no lo documentes formalmente.

---

5. El humano es director, no operador

Tu trabajo es decidir qué se hace, cuándo se valida, y si lo entregado es aceptable. NO es traducir entre el agente y el código. Si te encontrás ejecutando comandos que el agente podría ejecutar, parar y delegarlos.

Por qué: el humano operador es el cuello de botella del sistema. Cada minuto que pasás copiando-pegando, formateando outputs, o transportando contexto entre sesiones, es un minuto que no estás pensando en producto, arquitectura, o estrategia. El humano vale por su criterio, no por su throughput.

Cómo se aplica:

• Si el prompt se puede pre-armar en archivo, hacelo. No lo tipees cada vez.
• Si la validación se puede automatizar (test, lint, screenshot), automatizala.
• 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

1. Especificación precede al código    →  evita falsos arranques
2. Validación humana es ojo           →  evita falsos cierres
3. Auditoría adversarial              →  evita aprobaciones engañosas
4. Decisiones como contratos          →  evita re-debate y deriva
5. Humano director, no operador       →  evita cuello de botella

Los principios 1-2 protegen las puntas (entrada y salida del trabajo). Los principios 3-4 protegen la mitad (cómo evaluamos y registramos). El principio 5 protege la sostenibilidad (que el método escale).

---

Política de iniciativa agéntica

Política operativa que define cuándo un agente puede actuar proactivamente y cuándo debe consultar antes. Complementa el Principio 5 (humano como director).

El problema que resuelve

Los agentes producen mejor con libertad para optimizar lo local. Pero libertad sin límites lleva a:

• Cambios silenciosos que el humano descubre por casualidad
• Pérdida de gobernanza sobre el producto
• Erosión de la marca, arquitectura, o datos sin que nadie lo decida explícitamente

La política clasifica los cambios proactivos por impacto y define el comportamiento esperado en cada nivel.

Clasificación de impacto

Nivel 1 — Trivial

Definición: cambio interno no visible al usuario, reversible sin costo, sin efecto en datos o arquitectura.

Ejemplos:

• Renombrar una variable interna por claridad
• Reordenar imports
• Mejorar legibilidad de un comentario
• Extraer una función helper si se usa 3+ veces

Política: ejecutar libremente. Mencionar al final del reporte solo si fueron varios cambios acumulados.

Nivel 2 — Visible reversible

Definición: cambio visible al usuario final pero sin afectar marca, datos, ni arquitectura. Reversión cuesta minutos, no horas.

Ejemplos:

• Mejorar wording de un mensaje de error
• Ajustar padding o spacing en un componente
• Agregar un tooltip explicativo donde falta
• Reordenar columnas de una tabla para mejor lectura

Política: ejecutar y mencionar explícitamente en el reporte final como "decisión proactiva tomada — validar/revertir". El humano puede aprobar retroactivamente o pedir reversión.

Nivel 3 — De marca, arquitectura o datos

Definición: cambio que afecta identidad de marca, estructura del sistema, o información del usuario. Reversión cuesta horas o más.

Ejemplos:

• Agregar texto de marca al footer (ej. "Hecho desde Paraguay 🇵🇾")
• Cambiar colores que afectan la paleta visual del producto
• Agregar nuevas dependencias (npm packages, fonts, libs)
• Modificar estructura de datos persistidos (DB, IndexedDB)
• Cambiar flujos de navegación o jerarquía de información
• Agregar/quitar features no listadas en el brief

Política: NO ejecutar. Consultar antes de proceder. El reporte debe incluir:

PROPUESTA DE CAMBIO NIVEL 3 — requiere aprobación antes de implementar

Cambio sugerido: [descripción]
Justificación: [por qué el agente lo considera valioso]
Impacto: [qué afecta]
Alternativa si se rechaza: [qué hacer en lugar]

El humano decide explícitamente si proceder.

Casos límite

"Es trivial técnicamente pero visible para el usuario"

Sube a Nivel 2. La visibilidad es el criterio dominante.

"El brief no lo prohíbe explícitamente"

Irrelevante. El brief define el scope positivo (qué hacer), no negativo (todo lo demás). Cualquier cambio fuera del scope explícito se clasifica por impacto y se aplica la política.

"El cliente / usuario lo va a agradecer"

No es justificación para Nivel 3. La gratitud retroactiva no compensa el costo de la decisión unilateral. Si el cambio es bueno, sobrevive a la consulta previa.

"Es para arreglar un bug que descubrí"

Bugs reales se arreglan. Pero bugs cosméticos o de UX suelen ser Nivel 2 y se reportan, no se silencian. Bugs de datos o seguridad son Nivel 3 y se consultan si requieren cambio de modelo.

Cómo se aplica esta política en la práctica

Para el agente

Antes de hacer un cambio fuera del scope explícito del prompt:

1. ¿Es trivial? → ejecutar
2. ¿Es visible pero reversible? → ejecutar y reportar explícitamente
3. ¿Afecta marca, arquitectura, datos? → consultar primero

Para el humano

Al revisar un reporte:

1. Buscar la sección "Decisiones tomadas por iniciativa"
2. Validar cada cambio Nivel 2 (aprobar o pedir reversión)
3. Si hay propuesta Nivel 3, decidir antes de aprobar la etapa
4. Si descubrís un cambio no reportado, es violación del patrón C.6 — registrar y discutir

Para el método

Esta política es viva. Si en práctica aparecen casos que no encajan claramente en los 3 niveles, documentar el caso y refinar la política. La política es herramienta, no dogma.

---

Cómo se relaciona con los 5 principios

• Principio 3 (Auditoría adversarial): la política le da al humano una sección concreta donde buscar cambios silenciosos.
• Principio 4 (Decisiones como contratos): los cambios Nivel 3 generan nuevas decisiones que se registran formalmente.
• Principio 5 (Humano director, no operador): la política preserva la autonomía agéntica útil sin perder gobernanza sobre el producto.