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

Patrones operativos

Aplicaciones concretas de los 5 principios. Estructurados por categoría operativa.

Estado de cada patrón: propuesto (validado en 1 proyecto) o estable (validado en 2+ proyectos).

A la fecha, todos los patrones aquí son propuestos. Caso de validación: InQ ROI Sprint 1.5.

---

Categoría A — Disciplina antes de codear

A.1 Brief versionado antes que código

Estado: propuesto · Deriva de: Principio 1

Todo sprint o cambio mayor arranca con un brief en sprints/sprint-N/BRIEF.md antes de pedirle algo a un agente. El brief define alcance, decisiones tomadas, criterios de éxito y lo que NO entra.

Indicador de aplicación correcta: podés iniciar una sesión nueva con Claude Code pasándole solo el path del brief y CLAUDE.md, sin contexto adicional, y empieza a trabajar correctamente.

Indicador de violación: el agente te hace preguntas que ya están respondidas en otro lugar (o peor, no las hace y asume).

---

A.2 Mockup como contrato visual

Estado: propuesto · Deriva de: Principio 1

Si el cambio es visual, antes de implementarlo se construye un mockup interactivo (HTML, Figma, Visualizer) que el humano aprueba. El mockup es el contrato: el agente lo replica, no lo interpreta libremente.

Indicador de aplicación correcta: cuando ves el output del agente, podés compararlo lado a lado con el mockup y la diferencia es marginal.

Indicador de violación: llegás a Etapa N de un rediseño visual y descubrís que el output "no tiene nada que ver" con lo que esperabas.

---

A.3 Roadmap explícito antes de arrancar

Estado: propuesto · Deriva de: Principios 1 y 4

Todo sprint con más de 3 etapas tiene un roadmap explícito desde el inicio. Cada etapa tiene expectativa calibrada de qué cambia y qué NO cambia respecto a la anterior.

Indicador de aplicación correcta: después de cada checkpoint, el resultado coincide con lo que esperabas ver, no te sorprende ni para bien ni para mal.

Indicador de violación: te sorprende negativamente un output intermedio porque pensabas que ya tenía X feature que en realidad está agendado 3 etapas después.

---

Categoría B — Operación con agentes

B.1 Prompt como artefacto del repo

Estado: propuesto · Deriva de: Principios 4 y 5

Cada etapa de trabajo agéntico tiene su prompt en sprints/sprint-N/ETAPA_X_PROMPT.md, versionado. El chat con el agente es puente entre el prompt y el reporte, no contenedor de la decisión.

Por qué: los prompts en archivo son auditables, editables antes de ejecutar, replicables, y no se pierden al cerrar la sesión.

Estructura mínima de un prompt de etapa:

1. Objetivo
2. Pre-requisitos / contexto previo
3. Decisiones ya tomadas (no consultar de nuevo)
4. Tareas concretas
5. Entregables (DoD checklist)
6. Qué reportar al final
7. Qué NO hacer en esta etapa

---

B.2 Mensaje inicial corto, contexto en archivos

Estado: propuesto · Deriva de: Principio 5

El mensaje al agente al arrancar una sesión es de 3-5 párrafos, NO el prompt entero pegado. Estructura:

1. "Procedé con etapa X"
2. Archivos a leer en orden
3. Confirmaciones que esperás antes de que empiece
4. Restricción de alcance ("no avances a Y sin OK")

Por qué: el contexto en archivos sobrevive a la sesión, queda versionado, y el agente lo consulta cuando lo necesita en vez de tenerlo permanentemente en ventana.

---

B.3 Decisiones tomadas como sección explícita

Estado: propuesto · Deriva de: Principio 4

En cada prompt de etapa, incluir sección "DECISIONES YA TOMADAS — no consultar de nuevo" con las definiciones cerradas. Esto impide que el agente vuelva a preguntar lo ya resuelto.

Ejemplo:

DECISIONES YA TOMADAS (no consultar de nuevo)
- Payback negativo → "Sin payback (costo aumenta)"
- Caracteres compactos: "<" y "~"
- Pluralización: siempre plural ("1.0 meses")

---

B.4 Reglas no negociables en CLAUDE.md

Estado: propuesto · Deriva de: Principio 4

Las reglas que aplican a TODO el proyecto van en CLAUDE.md, no solo en briefs específicos. El agente carga CLAUDE.md en cada sesión nueva por defecto.

Ejemplo de qué va ahí:

• Reglas de marca (cómo se escribe el nombre, qué colores)
• Restricciones de comportamiento (qué no decir, qué no asumir)
• Verificaciones obligatorias pre-entrega

---

Categoría C — Validación de output

C.1 Validación visual mandatoria del artefacto final

Estado: propuesto · Deriva de: Principio 2

Si el output de la etapa es un artefacto visible (PDF, screenshot, página renderizada, documento), el humano lo abre con sus ojos antes del OK. Tests verdes no es suficiente.

Tooling sugerido:

• PDFs/imágenes: Preview en Mac, visor PDF en Linux
• 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)

Estado: propuesto · Deriva de: Principios 2 y 3

Antes de declarar una etapa completada, el agente debe ejecutar validaciones programáticas, no solo confiar en tests unitarios. Para outputs visuales:

• Análisis de píxeles (¿están los colores esperados?)
• Text extraction (¿están las palabras clave?)
• Tamaño de archivo (¿es razonable?)
• Cantidad de páginas (¿coincide con el diseño?)

Por qué: un test unitario puede pasar mientras el output final está roto. La validación programática del artefacto cierra ese gap.

---

C.3 Auditoría adversarial al reporte

Estado: propuesto · Deriva de: Principio 3

Cuando llega un reporte de agente "todo OK", aplicar 3 preguntas:

1. ¿Los números reportados cuadran si recalculo o pido dump?
2. ¿El artefacto es el que pedí?
3. ¿Lo que no menciona podría ser relevante?

Casos típicos de detección:

• PDF de 36 KB con 4 páginas (es muy poco → algo no se renderizó)
• KPI con valor "0.0 meses" (numéricamente correcto pero confuso)
• Reporte que dice "PDF generado" sin abrir el PDF generado

---

C.4 Reporte con datos concretos, no descripciones (agente)

Estado: propuesto · Deriva de: Principio 3

Los reportes del agente deben incluir métricas concretas, no descripciones genéricas.

Mal reporte: "PDF generado correctamente, contiene todo lo esperado."

Buen reporte:

PDF generado: 78 KB, 4 páginas
- Página 1: KPI Hero + 4 cards secundarios + top 3 ahorros
- Página 2: tabla con 11 filas + footer
- Página 3: 3 secciones (composición, trayectoria, transparencia)
- Página 4: nota metodológica
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:

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

C.6 Iniciativa agéntica con consulta clasificada por impacto

Estado: propuesto · Deriva de: Principios 3, 4 y 5

Cuando el agente detecta una oportunidad de mejora fuera del scope del prompt, debe clasificar el impacto del cambio antes de proceder y actuar según la política definida en PRINCIPLES.md sección "Política de iniciativa agéntica".

Niveles de impacto:

1. Trivial (cambio interno, no visible al usuario, reversible sin costo) → ejecutar y reportar al final como "decisión menor tomada"

2. Visible reversible (cambio visible al usuario pero sin afectar marca, datos, ni arquitectura) → ejecutar, mencionar explícitamente en el reporte final como "decisión proactiva, validar/revertir"

3. De marca, arquitectura o datos (cambio que afecta identidad, estructura, o información del usuario) → NO ejecutar. Consultar antes de proceder.

Por qué: los agentes producen mejor cuando tienen libertad para optimizar lo local. Pero esa libertad sin límites lleva a cambios silenciosos que el humano descubre por casualidad. Una clasificación explícita preserva la velocidad agéntica sin perder gobernanza.

Caso real: InQ ROI Sprint 1.5 Etapa 3. Claude Code agregó "Hecho desde Paraguay 🇵🇾" al footer del web app sin estar en el brief. El cambio era razonable, alineado con identidad de marca, pero el humano lo descubrió revisando screenshots, no porque se reportara. Decisión retroactiva: mantener, pero documentar el patrón para que en el futuro este tipo de cambios (impacto nivel 3, afecta marca) sean consulta previa, no decisión unilateral.

Indicador de aplicación correcta:

• El reporte final del agente tiene una sección explícita "Decisiones tomadas por iniciativa" listando cambios fuera del scope
• Los cambios nivel 3 no se ejecutan sin consulta previa documentada
• El humano puede aprobar o revertir cambios nivel 2 sin tener que reconstruir contexto

Indicador de violación:

• Descubrir cambios en el output que no están ni en el prompt ni en el reporte
• Cambios de marca, arquitectura o datos ejecutados sin consulta previa
• "Pequeñas mejoras de UX" agregadas en silencio que cambian el comportamiento del producto

Relación con otros patrones:

• Complementa E.2 (Hallazgos no esperados) — pero E.2 es para descubrimientos pasivos (cosas que el agente notó), C.6 es para decisiones activas (cosas que el agente hizo).
• Refuerza C.3 (Auditoría adversarial) — provee al humano una sección concreta donde buscar cambios silenciosos.

Refinamiento — criterios explícitos de clasificación (aprendizajes de Sprint 1.5)

Durante Sprint 1.5 InQ ROI se detectaron dos casos de mala clasificación de impacto. A partir de esos casos, se refinaron los criterios para distinguir entre Niveles 1, 2 y 3:

Reglas de clasificación (en orden de evaluación)

Evaluar en este orden estricto. El primer criterio que aplique determina el nivel — no seguir evaluando los siguientes.

1. ¿El cambio resuelve un ítem listado en TECH_DEBT.md, BACKLOG.md, o archivos de planificación? → Nivel 3 (consulta previa). Sin importar el tamaño técnico.

Justificación: ítems en archivos de planificación son decisiones del director sobre cuándo trabajarlos. El agente no puede promover ítems al sprint en curso por iniciativa.

2. ¿El cambio choca con una restricción explícita del prompt de la etapa? → Nivel 3 (consulta previa). Sin excepciones.

Ejemplo de restricciones explícitas:

• "NO entra: X" en sección de alcance
• "NO tocar Y" en reglas operativas
• "X está agendado para Etapa Z" en decisiones tomadas

3. ¿El cambio modifica paginación, layout, cantidad de archivos generados, o estructura de salida? → Nivel 2 mínimo. Reportar.

4. ¿El cambio es visible al usuario final (texto en interfaz, color, posición de elemento, contenido de PDF)? → Nivel 2 mínimo. Reportar.

5. ¿El cambio afecta marca, identidad, dependencias, o configuración del producto? → Nivel 3 (consulta previa).

6. Si nada de lo anterior aplica → Nivel 1

Ejemplos válidos de Nivel 1:

• Renombrar variable interna por claridad
• Reordenar imports
• Mejorar comentario de código
• Extraer función helper usada en múltiples lugares
• Eliminar código muerto evidente (sin riesgo de uso futuro)
• Limpiar artefactos accidentales del refactor (variables void no usadas)

Argumentos que NO son justificación válida para Nivel 1

El agente puede invocar argumentos que parecen razonables pero violan los criterios de arriba:

• "Es mejora de legibilidad" → si afecta contenido visible, es Nivel 2 mínimo
• "Es consistencia con etapa anterior" → verificar si la etapa anterior fue autorizada o si también es adelanto silencioso (ver AP.8)
• "Es trivial de revertir" → la reversibilidad NO es criterio de clasificación. Cambios reversibles también pueden ser Nivel 3.
• "Resuelve un bug menor" → si el bug está documentado en TECH_DEBT.md, es Nivel 3
• "Es lo que el usuario esperaría" → eso es asumir. La política existe para no asumir.

Casos reales documentados (Sprint 1.5 InQ ROI)

Caso 1 (Etapa 5): compactación de páginas reportada como Nivel 1.

• Realidad: Nivel 2 mínimo (modificó paginación visible)
• Resultado: nota metodológica truncada, descubierto en validación visual
• Lección: paginación es estructura de salida, criterio 3 aplica

Caso 2 (Etapa 7-8): reescritura de fórmulas Σ → "SUM" reportada inicialmente sin clasificación, después como Nivel 1.

• Realidad: Nivel 3 (resolvía ítem de TECH_DEBT.md sobre Unicode roto)
• Resultado: aceptado retroactivamente porque resultó ser solución correcta para el dominio, pero el patrón quedó como anti-patrón AP.8
• Lección: ítem en TECH_DEBT.md activa criterio 1 directo, sin importar el tamaño

Implicancia para CLAUDE.md del proyecto

En el CLAUDE.md de cada proyecto, agregar a la sección "Política de iniciativa proactiva":

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

1. Verificá si el cambio está listado en TECH_DEBT.md, BACKLOG.md, o 
   archivos de planificación equivalentes. Si está, es Nivel 3 — consultá.

2. Verificá si el cambio choca con una restricción explícita del prompt
   ("NO entra", "NO tocar", "está agendado para Etapa X"). Si choca, 
   es Nivel 3 — consultá.

3. Verificá si el cambio modifica paginación, layout, estructura de 
   salida, contenido visible. Si lo hace, es Nivel 2 mínimo — reportá.

4. Solo si nada de lo anterior aplica, ejecutá como Nivel 1.

Argumentos NO válidos para evitar la consulta:
- "Es mejora de legibilidad"
- "Es consistencia con etapa anterior" (verificar si esa etapa fue 
  autorizada o también fue adelanto silencioso)
- "Es trivial de revertir"
- "Resuelve un bug menor"

---

Categoría D — Estructura del repo

D.1 Carpeta sprints/ para activos de planificación

Estado: propuesto · Deriva de: Principio 4

Cada sprint tiene su carpeta sprints/sprint-N/ con todos sus artefactos:

• BRIEF.md
• ETAPA_X_PROMPT.md (uno por etapa)
• ETAPA_X_REPORT.md (opcional, reporte del agente capturado)
• etapa-X-audit.md (cuando aplica)
• screenshots/ con evidencia visual

Por qué: en 6 meses, abrir esa carpeta te da el historial completo de cómo se construyó el sprint. Sin esto, el conocimiento queda en commits + memoria, que es frágil.

---

D.2 Carpeta methodology/ para el método en sí

Estado: propuesto · Deriva de: Principio 4

El método de trabajo vive en methodology/, separado del producto. Esto permite que el método evolucione independiente de cualquier producto específico.

---

D.3 ADRs para decisiones arquitectónicas

Estado: propuesto · Deriva de: Principio 4

Las decisiones arquitectónicas importantes se registran como ADR (Architectural Decision Record) en ARCHITECTURE.md o docs/adr/. Estructura mínima:

• Contexto (qué problema teníamos)
• Decisión (qué elegimos)
• Alternativas consideradas
• Consecuencias (qué implica)

---

D.4 Permisos del agente versionados en .claude/

Estado: propuesto · Deriva de: Principios 4 y 5

Las decisiones sobre qué comandos puede ejecutar el agente sin consultar al humano se versionan en archivos de configuración del repo. Esto evita dos extremos: la fricción de aprobar cada comando manualmente, y el bypass total que abre la puerta a acciones no intencionadas.

Estructura recomendada:

repo/
└── .claude/
    ├── settings.json          ← commitable: deny patterns críticos
    └── settings.local.json    ← gitignored: allow personales del dev

Reglas:

1. settings.json es del proyecto — contiene patrones deny (comandos peligrosos prohibidos para todos: rm -rf /, git push --force, npm publish, etc.). Se comitea al repo.

2. settings.local.json es del desarrollador — contiene patrones allow personales (cada uno decide qué comandos pre-aprueba). Va en .gitignore. Cuando un dev nuevo arranca, debe construir su propio archivo siguiendo el template, no copiar el de otro.

3. El equipo hereda las protecciones, no las preferencias — los deny son compartidos, los allow son individuales.

Por qué:

• La fricción de aprobar cada npm install destruye el flow de trabajo
• Pero el bypass total elimina los puntos de control donde se detectan acciones no intencionadas
• La gobernanza está en clasificar comandos por riesgo, no en aprobar todo o aprobar nada

Indicador de aplicación correcta:

• En cada sesión de Claude Code, los comandos rutinarios pasan sin pedir aprobación
• Los comandos no rutinarios siguen pidiendo aprobación (es bueno — ahí prestás atención)
• Si un comando peligroso aparece, está bloqueado por deny o pide aprobación explícita

Indicador de violación:

• El dev usa --dangerously-skip-permissions rutinariamente
• El archivo settings.json contiene allow que deberían ser personales (paga la complejidad de mantenerlo sincronizado entre devs)
• No hay archivo de configuración y cada dev aprueba todo manualmente cada vez (fricción crónica, señal de que falta este patrón)

Template: ver methodology/TEMPLATES/CLAUDE_PERMISSIONS_TEMPLATE.md.

Relación con otros patrones:

• Complementa B.4 (reglas no negociables en CLAUDE.md) — pero B.4 es sobre comportamiento del agente, D.4 es sobre permisos del sistema operativo
• Refuerza Principio 5 (humano director) — sin permisos configurados, el dev se vuelve operador de aprobación

Casos reales que valida:

• InQ ROI: el director identificó fatiga de aprobación después de ~30 etapas. Configurar permisos eliminó la fricción sin perder gobernanza.

Categoría E — Comunicación humano ↔ agente

E.1 Separar lo validado de lo asumido

Estado: propuesto · Deriva de: Principios 2 y 3

En los reportes del agente, marcar explícitamente qué fue verificado vs qué se asume funcionando.

Ejemplo:

Verificado:
- Tests verdes (455/455)
- PDF generado y abierto con pdf-parse
- Análisis de píxeles confirma heatmap completo

Asumido:
- El componente se renderiza igual en Firefox (solo testeado en Chromium)
- La fuente Roboto está disponible en el sistema cliente (no validado)

---

E.2 Hallazgos no esperados como sección explícita

Estado: propuesto · Deriva de: Principios 3 y 5

Al final de cada etapa, el agente reporta "hallazgos no esperados" — cosas que descubrió durante la implementación que merecen decisión arquitectónica, aunque no formen parte del DoD.

Ejemplo: "El cambio de --primary propagó a focus rings de inputs (no estaba en el plan). Decisión necesaria: ¿se mantiene o se vuelve a slate?"

---

E.3 Anti-racionalización explícita

Estado: propuesto · Deriva de: Principio 3

Cuando un test revela algo raro, un cálculo no cuadra, o un output difiere de lo esperado: investigar causa raíz, no minimizar.

Patrón típico de violación: el agente dice "el cálculo es numéricamente correcto" cuando lo que está reportando es un problema de presentación (ej. "0.0 meses" es matemáticamente correcto pero un bug de UX).

---

Cómo agregar un patrón nuevo

1. Identificar el patrón durante un proyecto real (no inventarlo en abstracto).
2. Documentarlo con: nombre, categoría, principio del que deriva, descripción, indicador de aplicación correcta, indicador de violación.
3. Marcarlo como propuesto con cita del proyecto donde apareció.
4. Después de aplicarlo en un 2do proyecto distinto, promoverlo a estable.

Cómo retirar un patrón

Si un patrón no se sostiene en práctica o tiene falsos positivos frecuentes, se retira con un PR que documente:

• Por qué no funcionó
• Qué alternativa probamos
• Si hay un patrón nuevo que lo reemplaza