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ó.

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?

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).