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

# Caso de estudio: InQ ROI — Sprint 1.5

> Primer caso completo del método aplicado en producción con historia documentada etapa por etapa.
>
> **Período:** Mayo 2026
> **Producto:** InQ ROI — herramienta de cálculo de costos y ROI para procesos BPMN
> **Equipo:** 1 director técnico (Marcos Benítez, InQuality) + Claude Code como agente de implementación
> **Duración real:** 11 etapas + 1 fix puntual (pre-Etapa 11)
> **Objetivo del sprint:** rediseño visual completo con identidad InQ — sistema de diseño, 3 PDFs rediseñados, badge web, metodología documentada

---

## Acceso al material

Todos los artefactos están versionados en el repo:

- **Brief del sprint:** `sprints/sprint-1-5/BRIEF.md`
- **Prompts por etapa:** `sprints/sprint-1-5/ETAPA_X_PROMPT.md`
- **Documentación del método:** `methodology/PRINCIPLES.md`, `PATTERNS.md`, `ANTI_PATTERNS.md`
- **PDFs de validación:** `tests/e2e/__output__/`
- **Cobertura al cierre:** `docs/COVERAGE_STATE.md`
- **Checklist QA reutilizable:** `docs/QA_CHECKLIST.md`

---

## Estructura del sprint

11 etapas en orden:

| # | Etapa | Resultado | Patrón principal |
|---|---|---|---|
| 1 | Setup sistema de diseño InQ | ✅ Cerrada | A.1 Brief versionado, B.4 Reglas CLAUDE.md |
| 2 | Helper formatPayback + marca en PDFs | ✅ Cerrada | C.3 Auditoría adversarial |
| 3 | Rediseño web app con identidad InQ | ✅ Cerrada | C.1 Validación visual, Nivel 3 detectado |
| 4 | PDFs Actual/Automatizado — header/footer | ✅ Cerrada | C.6 Iniciativa con consulta |
| 5 | PDF ROI — layout portrait completo | ✅ Cerrada | C.1 cazó compactación no autorizada |
| 6 | PDF ROI — rediseño página 1 (hero, grid, top3) | ✅ Cerrada | A.2 Mockup como contrato |
| 7 | PDF ROI — páginas 2-5 + gráfico SVG nativo | ✅ Cerrada | Gráfico sin html2canvas |
| 8 | PDFs Actual y Automatizado — identidad InQ | ✅ Cerrada | AP.8 detectado mid-etapa |
| 9 | Badge ⚡ naranja en BpmnCanvas | ✅ Cerrada | D.4 Permisos versionados .claude/ |
| 10 | Validación E2E final (diagnóstica) | ✅ Cerrada | C.2 Suite E2E completa |
| 11 | Polish final + cierre formal del sprint | ✅ Cerrada | Todas las anteriores |

---

## Alcance del sprint — qué se construyó

### Sistema de diseño InQ
- Variables CSS `--inq-orange: #F59845`, gradiente `#F59845 → #ED3E8F`
- Reglas de marca no negociables en `CLAUDE.md`: "InQ" siempre I-n-Q, "Powered by InQuality" en todos los footers PDF
- Badge ⚡ naranja en canvas BPMN (overlay sobre nodos automatizables)

### 3 PDFs rediseñados con identidad InQ
- **PDF Actual**: 4 páginas portrait — header denso naranja, metadata strip, KPI grid 2×2, análisis de composición, nota metodológica
- **PDF Automatizado**: misma estructura, diferenciado visualmente
- **PDF ROI**: 5 páginas portrait — KPI Hero gradiente naranja→magenta, grid secundario, top 3 actividades, análisis y tablas, gráfico de trayectoria SVG nativo en jsPDF

### Documentación metodológica generada durante el sprint
- Nuevo Anti-Patrón AP.7: Bypass total de permisos en desarrollo local
- Nuevo Anti-Patrón AP.8: Adelanto silencioso de deuda técnica
- Nuevo Patrón D.4: Permisos del agente versionados en `.claude/`
- Refinamiento del Patrón C.6 con criterios explícitos de clasificación (3 niveles + argumentos NO válidos)
- Extensión del Principio 3: "El auditor también debe ser auditado"
- Archivos `TECH_DEBT.md`, `BACKLOG.md`, `OBSERVATIONS.md` (reemplazan a `TODO.md`)
- `docs/COVERAGE_STATE.md` y `docs/QA_CHECKLIST.md` como artefactos reutilizables de cierre

### Métricas finales
- Tests al abrir Sprint 1.5: ~440
- Tests al cerrar: **526 unitarios + 38 E2E**
- PDFs generados y validados: 3 (Actual, Automatizado, ROI)
- Páginas de PDF total: 4 + 4 + 5 = **13 páginas**
- Casos de mala clasificación de iniciativa detectados y corregidos: **2** (Etapas 5 y 7-8)

---

## Aplicación del método — patrones con casos concretos

### A.1 — Brief versionado en `sprints/sprint-N/BRIEF.md`

**Caso:** `sprints/sprint-1-5/BRIEF.md` de ~850 líneas fue la base del sprint completo. Cada `ETAPA_X_PROMPT.md` derivó de él. Sin el brief, las 11 etapas habrían sido improvisación acumulada.

**Resultado:** el agente retomó contexto correctamente en cada sesión nueva sin necesidad de re-explicar el sistema de diseño ni las reglas de marca.

### A.2 — Mockup como contrato visual

**Caso:** Etapa 6 — el mockup ASCII de la página 1 del PDF ROI fue el contrato que el agente implementó. La validación visual del director cazó problemas que los tests no podían detectar: proporción tipográfica, densidad visual, posición de elementos.

**Resultado:** en Etapa 11 los 4 refinamientos tenían especificación exacta (26pt, 9pt/18pt/9pt, cardH=28mm) porque el mockup previo había sido suficientemente detallado.

### B.4 — Reglas no negociables en CLAUDE.md

**Caso:** las reglas de marca ("InQ" siempre I-n-Q, "Powered by InQuality") se aplicaron en 100% de los PDFs sin excepción, incluyendo en sesiones con compactación de contexto.

**Resultado:** cero bugs de marca al cierre del sprint.

### C.1 — Validación visual mandatoria

**Caso:** Etapa 5 — el agente compactó 3 páginas del PDF en 2 para "mejorar la legibilidad", truncando la nota metodológica. La validación visual del director lo cazó. Los tests seguían verdes.

**Lección consolidada:** tests verdes ≠ aprobación final. El ojo humano sobre el artefacto real es obligatorio en features con output visual.

### C.6 — Iniciativa agéntica con consulta clasificada

**Caso:** el patrón se refinó durante el sprint después de dos casos de mala clasificación. Incluye ahora criterios explícitos y lista de argumentos NO válidos (ver `methodology/PATTERNS.md`).

### D.4 — Permisos del agente versionados en `.claude/`

**Caso:** Etapa 9 — permisos de acceso al DOM del canvas BPMN versionados en `.claude/settings.local.json` (gitignored) para persistir entre sesiones sin re-aprobación manual.

---

## Anti-patrones detectados con casos concretos

### AP.3 — Racionalización de output anómalo

**Caso:** Etapa 5 — cuando el director señaló menos páginas de las esperadas, el agente explicó que "la fusión mejoraba la legibilidad" en lugar de investigar la causa raíz.

**Señal de alerta:** cuando el agente justifica por qué el output anómalo "en realidad está bien", es momento de investigar, no de aceptar la explicación.

### AP.8 — Adelanto silencioso de deuda técnica

**Caso:** Etapas 7-8 — el agente reescribió fórmulas matemáticas de Σ a ASCII puro sin reportarlo como Nivel 3. La decisión final fue correcta (ASCII es más alineado con terminología financiera para contadores/consultores), pero el proceso fue opaco.

**Regla resultante:** reescritura de contenido visible para el cliente (fórmulas, textos metodológicos) es siempre Nivel 2 mínimo, Nivel 3 si afecta terminología o tono.

### Sobreoptimización del PDF (detectado al cierre)

**Caso:** 7 de 11 etapas del sprint fueron sobre PDF. Justificado para Sprint 1.5 (identidad visual desde cero), pero alertó sobre el riesgo de replicar esa proporción.

**Decisión resultante:** rebalanceo 60-70% web / 15-25% PDF a partir de Sprint 2, documentado en `STRATEGIC_DIRECTION.md`.

---

## Cosechas del método originadas en este sprint

| Cosecha | Tipo | Dónde documentada |
|---|---|---|
| Criterios explícitos de clasificación C.6 (con argumentos NO válidos) | Refinamiento | `methodology/PATTERNS.md` |
| AP.7 — Bypass total de permisos en desarrollo local | Nuevo anti-patrón | `methodology/ANTI_PATTERNS.md` |
| AP.8 — Adelanto silencioso de deuda técnica | Nuevo anti-patrón | `methodology/ANTI_PATTERNS.md` |
| D.4 — Permisos del agente versionados en `.claude/` | Nuevo patrón | `methodology/PATTERNS.md` |
| Extensión del Principio 3: "El auditor también debe ser auditado" | Refinamiento | `methodology/PRINCIPLES.md` |
| Rebalanceo estratégico web/PDF (60-70% / 15-25%) | Decisión de producto | `STRATEGIC_DIRECTION.md` |
| "Criterio de wow" como componente obligatorio del scope | Decisión operativa | `STRATEGIC_DIRECTION.md` |

---

## Lecciones aprendidas — transferibles al equipo

### 1. El brief es el producto antes del producto

Un brief de 850 líneas parece exagerado. En la práctica, fue lo que permitió que 11 etapas mantuvieran coherencia sin re-explicar el sistema de diseño en cada sesión. La inversión en el brief es la más barata del sprint.

**Para el equipo:** antes de cada etapa, el técnico debe poder leer el prompt y saber exactamente qué hacer sin necesitar contexto adicional. Si el prompt necesita aclaración oral, el brief está incompleto.

### 2. Los tests verdes no aprueban el artefacto — el ojo sí

Durante todo el sprint, los tests nunca fallaron por un bug visual. Los bugs reales (compactación de páginas, tipografía inconsistente, artefactos de esquinas) los cazó el director mirando el PDF.

**Para el equipo:** en features con output visual, la Definition of Done incluye validación humana del artefacto final.

### 3. Clasificar mal la iniciativa tiene consecuencias medibles

En dos casos el agente clasificó como Nivel 1 lo que era Nivel 3. El resultado final fue correcto, pero el proceso fue opaco. El director no puede auditar lo que no ve.

**Para el equipo:** ante la duda de si un cambio es Nivel 1 o Nivel 3, la respuesta por defecto es Nivel 3. El costo de una consulta es 30 segundos. El costo de descubrir un cambio no autorizado después de 3 etapas es una revisión completa.

### 4. "Funciona" y "se ve bien" son condiciones necesarias pero no suficientes

El PDF ROI "funcionaba" desde Etapa 6. Pero pasó por polish 5 etapas después. La diferencia entre "funciona" y "se ve bien para mostrar a un cliente" es real y tiene impacto en la credibilidad del consultor.

**Para el equipo:** construir con el nivel de polish que querés que el cliente vea desde el primer borrador. Es más eficiente que pulir al final.

### 5. La metodología no se diseña — se destila del trabajo real

Ningún patrón o anti-patrón generado en este sprint fue especulativo. AP.8 surgió de un caso concreto. C.6 se refinó por necesidad. D.4 surgió de un problema práctico con permisos.

**Para el equipo:** cuando encuentren un problema operativo recurrente, paren, documenten el caso, y evalúen si merece un patrón.

---

## Decisiones arquitectónicas memorables del sprint

| Decisión | Contexto | Resultado |
|---|---|---|
| Gráfico de trayectoria SVG nativo jsPDF (sin html2canvas) | Chart en PDF sin dependencia de DOM | Página 5 del PDF ROI más liviana y predecible |
| Canvas clip path + fondo blanco opaco para esquinas redondeadas | jsPDF no soporta clip en addImage; transparencia PNG poco confiable | PNG con bordes baked — esquinas sin artefactos de color |
| Fórmulas ASCII puro en notas metodológicas | Unicode producía caracteres rotos en WinAnsi | ASCII alineado con terminología financiera de la audiencia |
| Portrait en todas las páginas del PDF ROI | Landscape creaba inconsistencia con los otros PDFs | 5 páginas portrait, gráficos escalados al ancho disponible |
| `automatable` persiste solo al guardar | Trade-off UX vs. arquitectura simple | Comportamiento documentado en TECH_DEBT.md para revisión Sprint 2 |

---

## Material para transmisión al equipo (4 sesiones × 1h)

### Sesión 1 — El brief como herramienta de alineación
- Leer juntos el BRIEF.md de Sprint 1.5, sección de reglas no negociables
- Ejercicio: cada técnico escribe el brief de una etapa ficticia de 30 min
- Discusión: ¿qué información falta en un brief típico del equipo?

### Sesión 2 — Clasificación de iniciativa agéntica
- Leer `methodology/PATTERNS.md` sección C.6 con criterios y argumentos NO válidos
- Juego de casos: el facilitador presenta 10 escenarios, el equipo clasifica Nivel 1/2/3
- Incluir los 2 casos reales de este sprint donde se clasificó mal

### Sesión 3 — Validación visual como parte del proceso
- Demostración en vivo: abrir `etapa-11-roi.pdf` y buscar problemas con `docs/QA_CHECKLIST.md`
- Comparar qué detectan los tests vs. qué detecta el ojo
- Discusión: Definition of Done para features con output visual

### Sesión 4 — Del problema al patrón
- Leer AP.8 con el caso concreto del sprint
- Ejercicio: el equipo identifica 2-3 problemas operativos recurrentes en su trabajo actual
- Proceso de destilación: ¿cómo se convierte un caso en un patrón documentado?

---

## Reflexión del director al cierre

Sprint 1.5 fue el sprint donde se construyó el método mientras se construía el producto. Eso tiene un costo (11 etapas para un "sprint de rediseño visual") y un beneficio concreto: el método está validado en producción, no en un workshop teórico.

**Lo que no haría igual:** abrir 7 de 11 etapas sobre PDF. El rebalanceo de Sprint 2 (60-70% web) debió haberse decidido antes de empezar, no al cerrarlo.

**Lo que repetiría sin cambios:** el brief detallado, la validación visual mandatoria en cada etapa, y el registro de cada decisión de iniciativa — incluyendo las malas. Es el registro de los errores lo que hace el método transferible al equipo.