docs(methodology): commit inicial del método de trabajo con agentes

methodology/PATTERNS.md

@@ -0,0 +1,253 @@
+# 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)
+
+---
+
+### 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"
+```
+
+---
+
+## 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