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

methodology/ANTI_PATTERNS.md

@@ -0,0 +1,101 @@
+# Anti-patrones
+
+> Comportamientos que producen daño concreto y deben evitarse. Cada uno está documentado con el caso real donde apareció.
+>
+> A diferencia de los patrones (que son propuestos hasta validación), los anti-patrones se documentan estables porque el daño ya está observado.
+
+---
+
+## AP.1 — Tests verdes como aprobación final
+
+**Comportamiento:** declarar una etapa terminada porque los tests pasaron, sin abrir el artefacto final con los ojos.
+
+**Daño concreto:** llegás a producción con outputs visuales rotos. Caso real (InQ ROI MVP): los tests E2E verificaban que el PDF se generaba y tenía las páginas esperadas, pero nadie abrió el PDF. El heatmap embebido estaba en blanco por un bug de timing en html2canvas. Se descubrió 2 días después cuando un consultor lo abrió.
+
+**Cómo detectarlo:** el reporte del agente dice "tests verdes, build limpio, PDF generado en X path" pero no incluye observaciones visuales del PDF.
+
+**Cómo evitarlo:** aplicar **Principio 2** (validación humana es ojo) y **Patrón C.1** (validación visual mandatoria).
+
+---
+
+## AP.2 — Pasamanos invertido (humano como operador)
+
+**Comportamiento:** el humano traduce manualmente entre dos agentes o entre agente y código. Copia outputs, formatea, transporta contexto entre sesiones.
+
+**Daño concreto:** el humano se vuelve cuello de botella del sistema. Lo peor: deja de pensar en arquitectura/producto y se concentra en operación. Caso real (InQ ROI Sprint 1.5, Etapa 5): el director del proyecto sintió "soy pasamanos" después de varios checkpoints transportando reportes de Claude Code al arquitecto.
+
+**Cómo detectarlo:** preguntate si lo que estás haciendo lo podría hacer un script o un prompt mejor estructurado. Si la respuesta es sí, estás en este anti-patrón.
+
+**Cómo evitarlo:** aplicar **Principio 5** (humano director). Mover lo operativo a archivos (prompts pre-armados, templates) y reservar el chat para decisiones reales.
+
+---
+
+## AP.3 — Racionalización de output anómalo
+
+**Comportamiento:** cuando un output del agente tiene una métrica anómala (PDF inusualmente liviano, número muy redondo, payback "0.0 meses"), el agente o el humano racionalizan ("numéricamente correcto", "es el caso esperado") en lugar de investigar la causa raíz.
+
+**Daño concreto:** bugs latentes que se descubren en producción. Caso real (InQ ROI Sprint 1.5, Etapa 4): el PDF de ROI pesaba 36 KB con 4 páginas (9 KB/página), comparado con 78 KB/3 páginas (26 KB/página) de los otros PDFs. El agente reportó "PDF generado". El humano paró y pidió investigar — había secciones que no se renderizaban.
+
+**Cómo detectarlo:** cualquier número que parezca "anómalo pero técnicamente válido". Especialmente: tamaños de archivo, payback inmediato, ROI extremo, métricas con muchos ceros.
+
+**Cómo evitarlo:** aplicar **Principio 3** (auditoría adversarial) y **Patrón E.3** (anti-racionalización explícita).
+
+---
+
+## AP.4 — Decisión recurrente no registrada
+
+**Comportamiento:** el agente vuelve a preguntar lo mismo en cada sesión nueva, o miembros del equipo asumen distinto porque la decisión no está documentada.
+
+**Daño concreto:** outputs inconsistentes entre etapas, tiempo perdido re-debatiendo, deriva del producto. Caso real (InQ ROI Sprint 1.5, varias etapas): cada vez que Claude Code iba a aplicar formato de cifras, había que recordarle si usaba separador europeo o americano. Hasta que se documentó en `CLAUDE.md`.
+
+**Cómo detectarlo:** el agente te hace una pregunta que ya respondiste en alguna sesión anterior.
+
+**Cómo evitarlo:** aplicar **Principio 4** (decisiones como contratos) y **Patrón B.3** (decisiones tomadas explícitas en cada prompt).
+
+---
+
+## AP.5 — Improvisación sin gobernanza
+
+**Comportamiento:** un equipo (o miembros individuales) usa agentes de IA sin método compartido. Cada uno improvisa con su herramienta preferida, sin briefs, sin validación estructurada, sin documentar decisiones.
+
+**Daño concreto:**
+1. Deuda técnica invisible: artefactos producidos por IA que nadie puede auditar después
+2. Aprendizaje no se acumula: descubrimientos individuales no se transfieren
+3. Calidad inconsistente y no atribuible
+4. Imposibilidad de mejorar sistemáticamente
+
+**Cómo detectarlo:** preguntá al equipo "¿cómo hicieron este artefacto con IA?" — si las respuestas son distintas y vagas, estás acá.
+
+**Cómo evitarlo:** este método entero está diseñado para evitarlo. Específicamente: empezar con **Principios 1 y 4**.
+
+---
+
+## AP.6 — Brief grande pegado en chat
+
+**Comportamiento:** pegar un brief de 800+ líneas en el chat del agente como mensaje inicial.
+
+**Daño concreto:**
+- Consume contexto innecesariamente
+- No es auditable después
+- Se pierde si la sesión se corta
+- Cuesta tokens repetirlo
+
+Caso real (InQ ROI Sprint 1.5): el primer intento fue pegar el BRIEF.md completo en chat. Se reemplazó por la estructura `sprints/sprint-N/` con archivos versionados, mensaje inicial corto referenciando paths.
+
+**Cómo detectarlo:** si tu mensaje inicial al agente tiene más de 30 líneas, probablemente estás en este anti-patrón.
+
+**Cómo evitarlo:** aplicar **Patrón B.1** (prompt como artefacto del repo) y **Patrón B.2** (mensaje inicial corto).
+
+---
+
+## Cómo agregar un anti-patrón
+
+Solo se agregan anti-patrones con daño concreto observado, no especulativo. Estructura obligatoria:
+
+1. **Nombre breve** (forma de "AP.N — Descripción")
+2. **Comportamiento:** descripción de la acción problemática
+3. **Daño concreto:** qué pasa cuando ocurre, con caso real citado
+4. **Cómo detectarlo:** señal observable
+5. **Cómo evitarlo:** principio o patrón que lo previene
+
+No agregar anti-patrones de "esto sería malo si pasara" — solo de cosas que **pasaron en proyectos reales** del equipo.

methodology/CASE_STUDIES/inq-roi-sprint-1-5.md

@@ -0,0 +1,90 @@
+# Caso de estudio: InQ ROI Sprint 1.5
+
+> Primer caso completo del método aplicado en producción.
+>
+> **Período:** Mayo 2026
+> **Producto:** InQ ROI — herramienta de cálculo de costos y ROI para procesos BPMN
+> **Equipo:** 1 director técnico + Claude Code como agente de implementación
+> **Duración real:** ~ [completar al cierre]
+> **Sprint objetivo:** rediseño visual completo del producto con manual de marca InQ
+
+---
+
+## Acceso al material
+
+Todos los artefactos del sprint están versionados en el repo del producto:
+
+- **Brief del sprint:** `sprints/sprint-1-5/BRIEF.md`
+- **Prompts por etapa:** `sprints/sprint-1-5/ETAPA_X_PROMPT.md`
+- **Reportes por etapa:** `sprints/sprint-1-5/ETAPA_X_REPORT.md` (cuando se capturen)
+- **Audits:** `sprints/sprint-1-5/etapa-X-audit.md`
+- **Screenshots:** `tests/screenshots/etapa-X/`
+- **PDFs generados:** `tests/e2e/__output__/`
+
+---
+
+## Estructura del sprint
+
+11 etapas en orden:
+
+| # | Etapa | Estado | Patrón principal aplicado |
+|---|---|---|---|
+| 1 | Setup del sistema de diseño | ✅ Cerrada | A.1, B.4 |
+| 2 | Helper formatPayback + aplicación | ✅ Cerrada | C.3, E.1 |
+| 3 | Rediseño web app con identidad InQ | 🔄 En curso | C.1, C.4 |
+| 4 | PDF: header y footer compartidos | ⏳ Pendiente | |
+| 5 | PDF: layout híbrido portrait + landscape | ⏳ Pendiente | |
+| 6 | PDF: rediseño página 1 ROI | ⏳ Pendiente | |
+| 7 | PDF: páginas 3 y 4 ROI | ⏳ Pendiente | |
+| 8 | PDFs de Actual y Automatizado | ⏳ Pendiente | |
+| 9 | Badge ⚡ en BpmnCanvas | ⏳ Pendiente | |
+| 10 | Validación E2E final | ⏳ Pendiente | |
+| 11 | Documentación + Deploy | ⏳ Pendiente | |
+
+---
+
+## Lecciones documentadas
+
+### Patrones validados durante este caso
+
+[Se completa al cierre del sprint con la lista de patrones que se validaron en práctica]
+
+### Anti-patrones cazados durante este caso
+
+- **AP.1 — Tests verdes como aprobación final**: caso del PDF de heatmap embebido en blanco (origen en MVP previo al sprint)
+- **AP.2 — Pasamanos invertido**: notado por el director en Etapa 5, llevó a discusión meta sobre el método
+- **AP.3 — Racionalización de output anómalo**: PDF de 36 KB con 4 páginas (Etapa 4 inicial)
+- **AP.6 — Brief grande pegado en chat**: corregido a estructura `sprints/sprint-N/`
+
+### Decisiones arquitectónicas memorables
+
+- Heatmap saturado en lugar de pastel (decisión consciente vs propuesta inicial)
+- Layout híbrido portrait + landscape en PDFs (resolución del problema "diagramas BPMN no entran en A4 vertical")
+- font-weight 700 en CTAs para remediación WCAG parcial
+- Carátula del PDF eliminada — info integrada en header de página 1
+
+### Decisiones de producto memorables
+
+- Posicionamiento como herramienta interna de InQuality (no producto independiente)
+- Identidad propia (naranja) diferenciada de CONCILIA (morado) manteniendo familia visual
+- Regla de marca no negociable: "InQ" siempre I-n-Q
+- Detector de ROI inusual (>1000%) como feature de transparencia
+
+---
+
+## Métricas finales del sprint
+
+[Completar al cierre]
+
+- Cantidad de tests al inicio del sprint: 440
+- Cantidad de tests al cierre: [N]
+- Tamaño promedio de PDF inicial: [KB]
+- Tamaño promedio de PDF final: [KB]
+- Cantidad de screenshots de validación capturados: [N]
+- Cantidad de iteraciones de mockup: [N]
+
+---
+
+## Reflexión final
+
+[Completar al cierre del sprint con observaciones del director sobre qué funcionó, qué no, y qué cambiaríamos para el próximo proyecto]

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

methodology/PRINCIPLES.md

@@ -0,0 +1,90 @@
+# 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.
+
+**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.
+
+---
+
+## 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).

methodology/README.md

@@ -0,0 +1,54 @@
+# Método de trabajo con agentes de IA
+
+> Versión de trabajo. Nombre definitivo pendiente.
+>
+> Estado: **borrador en construcción**. Los patrones se validan en proyectos reales antes de promoverse a versión estable.
+
+---
+
+## Qué es esto
+
+Es el método interno de trabajo para construir software con agentes de IA (Claude Code y otros) manteniendo gobernanza, calidad y aprendizaje acumulado.
+
+**Hipótesis central:** los agentes de IA permiten producir software 5-10× más rápido que un desarrollador solo, pero **sin gobernanza producen deuda invisible que cuesta más caro de la que se ahorra**. Este método es el sistema de gobernanza.
+
+## Qué NO es
+
+- No es un manual de Claude Code. No enseña a usar la herramienta.
+- No es una metodología ágil reemplazante. Es complementario a Scrum/Kanban/lo que uses.
+- No es opcional dentro de InQuality cuando el output va a cliente o producción.
+
+## Para quién
+
+- Desarrolladores con experiencia técnica (programadores, ingenieros, analistas) que ya entienden conceptos de software (commits, tests, refactor, deuda técnica).
+- Líderes técnicos que orquestan equipos pequeños (2-10 personas) trabajando con agentes.
+
+## Cómo se usa este repositorio
+
+Lectura en orden recomendado:
+
+1. **PRINCIPLES.md** — los 5 principios fundamentales. Es lo único memorizado obligatorio.
+2. **PATTERNS.md** — los patrones operativos derivados. Es referencia, no memoria.
+3. **ANTI_PATTERNS.md** — qué evitar y por qué. Útil para detectar problemas en flagrante.
+4. **TEMPLATES/** — scaffolds reutilizables para no empezar de cero.
+5. **CASE_STUDIES/** — proyectos reales aplicando el método. El primero es InQ ROI Sprint 1.5.
+
+## Cómo contribuir
+
+Si descubrís un patrón nuevo o un anti-patrón:
+
+1. Documentalo en su archivo correspondiente con la estructura existente
+2. Citá el contexto real donde lo encontraste (proyecto + sprint)
+3. Pull request con revisión de al menos otra persona del equipo
+
+Los patrones se validan en **al menos 2 proyectos distintos** antes de promoverse de "propuesto" a "estable".
+
+## Estado actual de madurez
+
+| Sección | Estado | Próxima revisión |
+|---|---|---|
+| Principios | Borrador inicial — 5 derivados de InQ ROI | Después de Sprint 2 con otro proyecto |
+| Patrones | 12 identificados, marcados como propuestos | Promover a estable los que se apliquen en 2do proyecto |
+| Anti-patrones | 5 identificados, todos en flagrante real | Estables — son daño documentado |
+| Templates | 3 disponibles (Brief, Prompt etapa, Reporte) | Iterar con uso real |
+| Case studies | 1 en construcción (InQ ROI Sprint 1.5) | — |

methodology/TEMPLATES/BRIEF_TEMPLATE.md

@@ -0,0 +1,83 @@
+# Sprint N — [Nombre descriptivo]
+
+> **Propósito:** [una oración que describe qué cambia con este sprint]
+>
+> **Justificación:** [por qué ahora, qué costo evita o qué oportunidad captura]
+
+---
+
+## 0. Contexto crítico
+
+[Cualquier información del producto, marca, o cliente que aplica transversalmente a todas las etapas. Reglas no negociables que el agente debe respetar.]
+
+---
+
+## 1. Alcance del sprint
+
+### Sí entra
+- [Feature o cambio 1]
+- [Feature o cambio 2]
+- ...
+
+### NO entra
+- [Cosa que podría parecer en alcance pero NO]
+- [Feature postergada con razón]
+- ...
+
+---
+
+## 2. Decisiones tomadas previamente
+
+| Decisión | Fuente / Justificación |
+|---|---|
+| [Decisión 1] | [Sprint o documento donde se decidió] |
+| [Decisión 2] | [...] |
+
+---
+
+## 3. Roadmap del sprint
+
+Lista ordenada de etapas con expectativa calibrada de cada una:
+
+| Etapa | Qué hace | Output esperado al final |
+|---|---|---|
+| 1 | [Descripción breve] | [Qué se ve, qué se mide] |
+| 2 | [...] | [...] |
+| ... | | |
+
+---
+
+## 4. Definition of Done del sprint completo
+
+```
+[ ] [Criterio mensurable 1]
+[ ] [Criterio mensurable 2]
+[ ] [Tests verdes esperados N]
+[ ] [Validación visual con usuario]
+[ ] [Documentación actualizada]
+[ ] [Tag de release X]
+```
+
+---
+
+## 5. Archivos que se crean / modifican (preview)
+
+### Nuevos
+- [Archivo + propósito]
+
+### Modificados
+- [Archivo + qué cambia en él]
+
+---
+
+## 6. Lo que NO entra en este sprint (postergado)
+
+- [Cosa importante que considerada y rechazada para este sprint, con justificación]
+
+---
+
+## Notas finales para el agente
+
+- [Recordatorios específicos del sprint]
+- [Cosas con las que el agente puede confundirse, aclaradas]
+- [Reglas operativas que aplican durante el sprint]

methodology/TEMPLATES/ETAPA_PROMPT_TEMPLATE.md

@@ -0,0 +1,105 @@
+# Sprint N — Etapa X: [Nombre descriptivo de la etapa]
+
+> **Objetivo:** [una oración que describe qué hace esta etapa específica]
+>
+> **Pre-requisitos:** [qué tiene que estar listo antes de arrancar; típicamente etapas previas]
+>
+> **Etapa siguiente:** [qué viene después, para que el agente NO arranque eso sin OK]
+
+---
+
+## 1. Pre-tareas (si aplica)
+
+[Actualizaciones a artefactos previos antes de la implementación. Por ejemplo: actualizar un audit, completar un documento de Etapa anterior.]
+
+### 1.1 [Pre-tarea 1]
+
+[Descripción concreta de qué hacer]
+
+### 1.2 [Pre-tarea 2]
+
+[...]
+
+---
+
+## 2. Decisiones ya tomadas (no consultar de nuevo)
+
+| Decisión | Justificación |
+|---|---|
+| [Decisión 1] | [Por qué se eligió esto y no la alternativa] |
+| [Decisión 2] | [...] |
+
+---
+
+## 3. Tarea principal
+
+### 3.1 [Subtarea 1]
+
+**Ubicación:** [archivo o módulo]
+
+**Descripción concreta:** [qué se implementa]
+
+**Snippet de referencia** (si aplica):
+```typescript
+// código de referencia
+```
+
+### 3.2 [Subtarea 2]
+
+[...]
+
+---
+
+## 4. Tests obligatorios
+
+### 4.1 Tests unitarios
+
+[Lista de casos a cubrir, con inputs y outputs esperados]
+
+### 4.2 Tests E2E o visuales (si aplica)
+
+[Lo que requiere validación end-to-end]
+
+---
+
+## 5. Aplicación en múltiples lugares (si aplica)
+
+[Si la tarea involucra cambios en múltiples capas, listarlas explícitamente]
+
+a) [Capa 1]: [qué cambia]
+b) [Capa 2]: [qué cambia]
+c) [Capa 3]: [qué cambia]
+
+---
+
+## 6. Entregables (Definition of Done)
+
+```
+[ ] [Criterio 1 — mensurable y específico]
+[ ] [Tests pasando: N esperados]
+[ ] [Build limpio]
+[ ] [Validación visual con artefactos concretos]
+[ ] [Documentación actualizada si aplica]
+```
+
+---
+
+## 7. Reporte final a entregar
+
+Cuando termines, devolveme:
+
+1. [Métrica concreta 1 — ej: tabla de tests con resultados]
+2. [Artefacto visible 1 — ej: screenshot del componente]
+3. [Artefacto visible 2 — ej: PDF presentado con present_files]
+4. [Cantidad final de algo mensurable]
+5. **Hallazgos no esperados** — cualquier descubrimiento que merezca decisión arquitectónica
+
+---
+
+## 8. Reglas operativas (recordatorios)
+
+1. **No declares etapa terminada sin validación visual** del artefacto final.
+2. **No racionalizar problemas** — si algo no cuadra, investigar causa raíz.
+3. **No tocar [lo que esta etapa NO debe tocar]** — está agendado para Etapa Y.
+4. **No avanzar a Etapa siguiente sin OK explícito.**
+5. **Si encontrás contradicción** entre este prompt y la realidad del código (un archivo no está donde decía, una función cambió de signature, etc.): **PARÁ y consultá**, no asumas.

methodology/TEMPLATES/REPORT_TEMPLATE.md

@@ -0,0 +1,100 @@
+# Sprint N — Etapa X: Reporte final
+
+> Reporte capturado al cierre de la etapa. Útil para auditoría y para reconstruir contexto en sesiones futuras.
+>
+> Generado por el agente, validado por el humano antes del commit.
+
+---
+
+## 1. Resumen de cambios
+
+### Archivos creados/modificados
+
+| Archivo | Acción | Líneas | Propósito |
+|---|---|---|---|
+| [path] | Creado/Modificado | +N/-M | [descripción breve] |
+
+---
+
+## 2. Tests
+
+### Resultados
+
+- Tests previos: N (sin regresión)
+- Tests nuevos: M
+- Total: N+M verdes
+
+### Tests nuevos agregados
+
+| Test | Caso | Resultado |
+|---|---|---|
+| [nombre] | [input → output esperado] | ✅ |
+
+---
+
+## 3. Artefactos visibles generados
+
+| Artefacto | Tamaño | Validación | Path |
+|---|---|---|---|
+| [PDF / screenshot / archivo] | XX KB | ✓ visualizado | [path] |
+
+---
+
+## 4. Verificación programática (si aplica)
+
+### Análisis de píxeles / contenido / métricas
+
+[Resultados concretos: qué se midió y qué dio]
+
+### Text extraction (si aplica)
+
+[Palabras clave esperadas confirmadas en el output]
+
+---
+
+## 5. Validado vs Asumido
+
+### Verificado
+- [Lista de cosas efectivamente comprobadas]
+
+### Asumido (no validado en esta etapa)
+- [Lista de cosas que se asumen funcionando pero no se probaron explícitamente]
+
+---
+
+## 6. Hallazgos no esperados
+
+[Cualquier descubrimiento durante la implementación que merezca decisión arquitectónica, aunque no esté en el DoD]
+
+- **Hallazgo 1:** [descripción]
+  - Impacto: [cuál]
+  - Decisión requerida: [qué tiene que decidir el humano]
+  - Sugerencia del agente: [recomendación]
+
+---
+
+## 7. Patrones aprendidos (cosecha para methodology/)
+
+[Si durante esta etapa surgió un patrón nuevo o se validó uno existente, registralo acá. El humano decide si pasa a `methodology/PATTERNS.md`.]
+
+- **Patrón candidato:** [descripción]
+  - Categoría: [A/B/C/D/E]
+  - Deriva de: [Principio N]
+  - Indicador de aplicación correcta: [...]
+  - Indicador de violación: [...]
+
+---
+
+## 8. Definition of Done — checklist final
+
+```
+[x] Criterio 1 cumplido
+[x] Criterio 2 cumplido
+[ ] Criterio 3 — pendiente porque [razón]
+```
+
+---
+
+## 9. Próximo paso
+
+[Qué viene después: etapa siguiente, decisión pendiente del humano, etc.]