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

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

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

---

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