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

---

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)

---

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