From 4f6c424d5c8930c40f588bf1075d1e066730ddec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20Ben=C3=ADtez?= Date: Tue, 19 May 2026 07:27:20 -0300 Subject: [PATCH] docs: cierre formal de Sprint 1.5 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - OBSERVATIONS.md reseteado para Sprint 2 - STRATEGIC_DIRECTION.md con reflexiones del sprint - TECH_DEBT.md curado: items resueltos archivados - methodology/CASE_STUDIES/inq-roi-sprint-1-5.md generado Sprint 1.5 cerrado: - 11 etapas + 1 fix pre-Etapa 11 - 526 unit tests + 38 E2E al cierre - Producto con identidad InQ aplicada en web + 3 PDFs - Metodología documentada con casos reales (2 de mala clasificación de iniciativa, originaron AP.8 + refinamiento C.6) - Material para transmisión al equipo de 5 técnicos --- OBSERVATIONS.md | 106 +------- STRATEGIC_DIRECTION.md | 55 +++- TECH_DEBT.md | 54 ++-- .../CASE_STUDIES/inq-roi-sprint-1-5.md | 242 ++++++++++++++---- 4 files changed, 282 insertions(+), 175 deletions(-) diff --git a/OBSERVATIONS.md b/OBSERVATIONS.md index 1ac08a9..676d009 100644 --- a/OBSERVATIONS.md +++ b/OBSERVATIONS.md @@ -1,13 +1,15 @@ -# OBSERVATIONS — Sprint 1.5 (Rediseño visual) +# OBSERVATIONS — Sprint 2 -> Hallazgos descubiertos durante validación visual del sprint actual. +> Hallazgos descubiertos durante el sprint actual. > Este archivo se vacía al cerrar el sprint: los hallazgos se promocionan a TECH_DEBT.md o BACKLOG.md, o quedan resueltos. +> +> **Sprint 1.5 cerrado el 2026-05-18.** Ver cierre en `methodology/CASE_STUDIES/inq-roi-sprint-1-5.md`. --- ## Convención de etiquetas -- `[CURRENT-SPRINT]` — Se resuelve en este sprint (Sprint 1.5) +- `[CURRENT-SPRINT]` — Se resuelve en este sprint - `[DEFERRED-TECH-DEBT]` — Se va a TECH_DEBT.md al cerrar el sprint - `[DEFERRED-BACKLOG]` — Se va a BACKLOG.md al cerrar el sprint - `[RESOLVED]` — Resuelto durante el sprint, archivar al cierre @@ -16,107 +18,25 @@ ## Hallazgos activos -### [CURRENT-SPRINT — POLISH FINAL] Refinamientos visuales página 1 PDF ROI -Detectados en validación visual de Etapa 6. -Se resuelven en polish final del sprint (Etapa 11). - -**Lista de refinamientos:** - -1. **KPI Hero**: spacing label-cifra, tamaño cifra, esquinas redondeadas -2. **Banner narrativo**: destacar cifras y keywords tipográficamente -3. **Grid 2x2 KPIs secundarios**: inconsistencia tipográfica entre cards -4. **Top 3 actividades**: título pequeño, barras sin contraste de fondo - -**Decisión:** todos los refinamientos van a Etapa 11 (polish final), no se abordan ahora para mantener ritmo del sprint. - -**Origen:** validación visual del director en cierre de Etapa 6. +*(Sin hallazgos al abrir Sprint 2 — archivo limpio)* --- ## Hallazgos resueltos durante el sprint -### [RESOLVED] Carácter Unicode `↓` roto en card AHORRO POR EJECUCIÓN -**Síntoma:** mostraba `!"` en lugar de `↓`. -**Resolución:** reemplazado por texto plano en Etapa 6 (fix post-validación). -**Sprint cerrado en:** Sprint 1.5 Etapa 6. - -### [RESOLVED] PDF generado del tab equivocado en E2E -**Síntoma:** test E2E generaba PDF del tab "Actual" en lugar de "Comparación + ROI". -**Resolución:** helper `setupRealisticScenario()` ahora navega al tab correcto antes del export. -**Sprint cerrado en:** Sprint 1.5 Etapa 2. - -### [RESOLVED] Strings de marca "Process Cost Platform" en footers PDF -**Síntoma:** footers seguían diciendo "Process Cost Platform" en lugar de "InQ ROI · Powered by InQuality". -**Resolución:** strings reemplazados en pdf-export.ts y pdf-sections-roi.ts. -**Sprint cerrado en:** Sprint 1.5 Etapa 2 (adelanto de Etapa 4). - -### [RESOLVED] Threshold "1.000,0%" con decimal en sección Transparencia -**Síntoma:** umbral de ROI inusual aparecía con decimal innecesario. -**Resolución:** usar `formatPercent(ROI_HIGH_THRESHOLD, 0)`. -**Sprint cerrado en:** Sprint 1.5 Etapa 2. - -### [RESOLVED] Decisión proactiva "Hecho desde Paraguay 🇵🇾" sin consulta -**Síntoma:** Claude Code agregó texto al footer del web app sin reportar. -**Resolución:** mantener decisión (aprobada retroactivamente). El cambio de método mayor fue la creación del Patrón C.6 (iniciativa agéntica con consulta clasificada). -**Sprint cerrado en:** Sprint 1.5 Etapa 3. - -### [RESOLVED] Compactación no autorizada de página 3 PDFs Actual/Automatizado -**Síntoma:** Claude Code fusionó "Análisis de composición + Tabla + Nota metodológica" en una sola página, truncando la nota metodológica. -**Resolución:** restauración de estructura 4 páginas con nota metodológica en página separada. -**Aprendizaje:** la decisión fue clasificada como Nivel 1 cuando era Nivel 2 mínimo. Reforzó el Patrón C.6 con criterios de clasificación explícitos. -**Sprint cerrado en:** Sprint 1.5 Etapa 5. - -### [RESOLVED] Reescritura de fórmulas Σ → ASCII puro en notas metodológicas - -**Síntoma:** durante Etapas 7 y 8, Claude Code reescribió las fórmulas -matemáticas de las notas metodológicas de los 3 PDFs (Σ → "SUM", × → "x", -− → "-"). El cambio en Etapa 7 pasó sin reporte. El cambio en Etapa 8 -fue reportado como Nivel 1 cuando era Nivel 3. - -**Resolución:** decisión arquitectónica retroactiva. La notación ASCII -pura es más alineada con terminología financiera/Excel (audiencia de -InQ ROI: contadores y consultores). Se acepta como solución permanente. - -**Consecuencia en TECH_DEBT.md:** el ítem "Sprint 2 — Fórmulas truncadas -+ Unicode roto" se reduce. Las fórmulas ya no necesitan font embedding -Unicode. Sigue pendiente investigar si hay truncamiento de líneas largas -en algún caso edge. - -**Aprendizaje meta:** dos casos de mala clasificación de iniciativa en -el sprint (Etapa 5 + Etapa 7-8). Originaron refinamiento del Patrón C.6 -y nuevo Anti-Patrón AP.8 (adelanto silencioso de deuda técnica). - -**Sprint cerrado en:** Sprint 1.5 Etapa 8. +*(vacío)* --- ## Hallazgos diferidos (promocionar al cerrar sprint) -### [DEFERRED-TECH-DEBT] Fórmulas truncadas + Unicode roto en notas metodológicas -Ya migrado a `TECH_DEBT.md` sección "Deuda crítica". Se mantiene acá como referencia hasta el cierre del sprint. - -**Plan:** Sprint 2, etapa dedicada a font embedding + text wrapping. - -### [DEFERRED-BACKLOG] Footer "Hecho desde Paraguay 🇵🇾" — destino final -Ya migrado a `BACKLOG.md` sección "Decisiones de producto pendientes". - -**Plan:** decidir en Sprint 3-4 con feedback real. - -### [DEFERRED-BACKLOG] CumulativeSavingsChart web — empezar en -inversión -Ya migrado a `TECH_DEBT.md` sección "Refinamientos UX". - -**Plan:** próxima etapa que toque el componente, o Sprint 2. - -### [DEFERRED-BACKLOG] Label "Payback" superpuesto en CumulativeSavingsChart -Ya migrado a `TECH_DEBT.md` sección "Refinamientos UX". - -**Plan:** próxima etapa que toque el componente. +*(vacío)* --- -## Notas operativas del sprint +## Notas operativas -- Los hallazgos resueltos quedan acá hasta el cierre del sprint. Al cerrar, se archiva el documento o se purga. +- Los hallazgos resueltos quedan acá hasta el cierre del sprint. Al cerrar, se archiva o purga. - Los hallazgos sin resolver se promocionan a `TECH_DEBT.md` o `BACKLOG.md` según corresponda. - Este archivo NO contiene roadmap futuro ni deuda histórica — solo hallazgos del sprint en curso. @@ -124,12 +44,12 @@ Ya migrado a `TECH_DEBT.md` sección "Refinamientos UX". ## Cierre del sprint (checklist) -Cuando Sprint 1.5 cierre, ejecutar: +Cuando el sprint cierre, ejecutar: ``` [ ] Verificar que todos los items [CURRENT-SPRINT] están RESOLVED [ ] Mover items [DEFERRED-TECH-DEBT] a TECH_DEBT.md (si no están ya) [ ] Mover items [DEFERRED-BACKLOG] a BACKLOG.md (si no están ya) [ ] Archivar o purgar este archivo -[ ] Crear OBSERVATIONS.md vacío para Sprint 2 -``` \ No newline at end of file +[ ] Crear OBSERVATIONS.md vacío para el sprint siguiente +``` diff --git a/STRATEGIC_DIRECTION.md b/STRATEGIC_DIRECTION.md index 7fcb2f8..b0f464e 100644 --- a/STRATEGIC_DIRECTION.md +++ b/STRATEGIC_DIRECTION.md @@ -164,4 +164,57 @@ Los patrones documentados en `methodology/` se validan en proyectos reales. No s - Confirmar que el rebalanceo web/PDF se respetó en Sprint 2 - Evaluar si "criterio de wow" funcionó como herramienta operativa - Refinar definiciones por consolidar (posicionamiento, métricas) con datos reales -- Capturar nuevas decisiones estratégicas surgidas durante el sprint \ No newline at end of file +- Capturar nuevas decisiones estratégicas surgidas durante el sprint + +--- + +## Reflexiones del cierre de Sprint 1.5 + +> Agregado el 2026-05-18 al cerrar formalmente el sprint. + +### Lo que funcionó bien + +**El brief como ancla de coherencia.** Las 11 etapas mantuvieron consistencia de marca, paleta y arquitectura sin re-explicar el contexto en cada sesión. El `BRIEF.md` de ~850 líneas más `CLAUDE.md` con reglas no negociables resultaron suficientes para que el agente retomara contexto en sesiones nuevas incluso con compactación de contexto. + +**La validación visual como capa de calidad independiente.** En dos casos los tests estaban 100% verdes pero el output visual tenía problemas reales: compactación de páginas (Etapa 5) y artefactos de esquinas en el KPI Hero (Etapa 11). La validación visual del director los cazó en ambos casos. Esta práctica se consolida como mandatoria en todos los sprints futuros. + +**La documentación del método en tiempo real.** AP.8, el refinamiento de C.6 y D.4 surgieron de problemas reales durante el sprint y se documentaron en el momento. El material resultante para transmisión al equipo es concreto, no especulativo. + +**Los PDFs como entregable de clase profesional.** Al cierre del sprint, los 3 PDFs tienen identidad visual coherente, son 100% reproducibles via E2E, y pasan inspección visual de nivel "presentable a cliente". Esto no era el caso al abrir el sprint. + +### Lo que costó más de lo esperado + +**Las esquinas redondeadas del KPI Hero.** 3 iteraciones para resolver un problema aparentemente simple: (1) overlay de rectángulos blancos + arcos naranja → colisión con el gradiente magenta en esquina derecha; (2) canvas clip con transparencia PNG → jsPDF no renderiza alpha correctamente; (3) canvas con fondo blanco opaco + clip → solución definitiva. El tiempo invertido fue desproporcionado al impacto visual. + +**La proporción PDF/web.** 7 de 11 etapas fueron sobre PDF. El rebalanceo debió haberse decidido en el brief del sprint, no al cerrarlo. La decisión de "establecer identidad visual desde cero" fue correcta para Sprint 1.5, pero el método de trabajo no contempló explícitamente el límite de inversión en PDF antes de empezar. + +**Los casos de mala clasificación de iniciativa.** Dos casos (Etapas 5 y 7-8) requirieron revisión retroactiva y discusión meta sobre el método. El costo no fue solo el tiempo de corrección, sino la incertidumbre sobre qué otros cambios podrían haberse aplicado sin consulta. Originaron el refinamiento más detallado del Patrón C.6. + +### Decisiones arquitectónicas tomadas en el sprint + +| Decisión | Estado al cierre | +|---|---| +| Gráfico de trayectoria SVG nativo en jsPDF (sin html2canvas) | Definitiva — aplicada en página 5 del PDF ROI | +| Fórmulas ASCII puro en notas metodológicas | Definitiva — alineada con terminología financiera de la audiencia | +| Portrait en todas las páginas del PDF ROI | Definitiva — consistencia con los otros PDFs | +| Canvas clip con fondo blanco para esquinas redondeadas | Definitiva — sin artefactos de color | +| `automatable` persiste solo al Guardar (no auto-save) | Provisional — revisar en Sprint 2 con feedback de uso real | + +### Estado de definiciones del producto al cierre de Sprint 1.5 + +**Estables (no se reabren):** +- Identidad visual completa: paleta naranja, gradiente, reglas de marca +- Stack tecnológico: sin cambios respecto al MVP +- Modelo de escenarios: Modelo A (dos campos por actividad, un BPMN) +- ROI: cálculos nominales simples sin VPN ni Monte Carlo + +**Pendientes de input externo:** +- Posicionamiento de mercado (¿herramienta interna o venta a otras consultoras?) +- Métricas de éxito del producto (post-Sprint 2 con datos reales de uso) +- Nombre comercial definitivo ("InQ ROI" es nombre de trabajo) +- Manual de marca formal de InQuality (cuando exista, se incorpora) + +**Nueva prioridad para Sprint 2:** +- Rebalanceo web/PDF: 60-70% features de web app, 15-25% PDF +- Criterio de wow obligatorio en cada ETAPA_PROMPT.md +- Feedback de uso real en talleres InQuality como insumo para decisiones de UX \ No newline at end of file diff --git a/TECH_DEBT.md b/TECH_DEBT.md index f7085cc..e61f2ab 100644 --- a/TECH_DEBT.md +++ b/TECH_DEBT.md @@ -108,32 +108,6 @@ asignar etapa de Sprint 2. --- -## Refinamientos visuales del PDF — derivados de validaciones de Sprint 1.5 - -> Estos hallazgos surgieron en validaciones visuales del director durante Sprint 1.5. Se difirieron a "polish final" del mismo sprint o a Sprint 2. - -### [SPRINT-1.5 — POLISH FINAL] Refinamientos página 1 PDF ROI - -**KPI Hero:** -- Spacing entre label "AHORRO PROYECTADO A 3 AÑOS" y la cifra -- Tamaño de la cifra (evaluar reducir ligeramente) -- Esquinas redondeadas (si se logra técnicamente — jsPDF no hace clip en addImage) - -**Banner narrativo:** -- Destacar tipográficamente cifras y palabras clave (negrita en USD, %, meses) -- Considerar bullets o estructura más visual - -**Grid 2x2 KPIs secundarios:** -- Inconsistencia tipográfica detectada — investigar y armonizar -- Verificar que los 4 cards sigan el mismo patrón visual - -**Top 3 actividades:** -- Aumentar tamaño del título "TOP 3 ACTIVIDADES POR AHORRO" -- Agregar fondo claro a las barras para mejor contraste -- Reconsiderar diseño completo del bloque - ---- - ## Decisiones arquitectónicas tomadas en Sprint 1.5 (cerradas, archivadas) > Sección informativa. Estas decisiones ya están aplicadas en el código. Se mantienen acá como referencia. @@ -148,4 +122,30 @@ Decidido: el KPI "Costo total" se migró a naranja durante refactor de Sprint 1. Decidido: en filas donde `isAutomatable === false`, mostrar "—" (em dash) en columnas Ahorro y % Ahorro en lugar de "USD 0,00" y "0,0%". Aplicado en Sprint 1.5. ### Versión "v0.1.0" en footer — fuera de PDFs, presente en web -Decidido: la versión es útil para usuarios internos en web. En PDFs entregados a clientes genera dudas de estabilidad. Aplicado en Sprint 1.5. \ No newline at end of file +Decidido: la versión es útil para usuarios internos en web. En PDFs entregados a clientes genera dudas de estabilidad. Aplicado en Sprint 1.5. + +--- + +### Anotaciones rápidas antes de pasar a Etapa 10 + +### [BACKLOG] Tamaño del badge ⚡ — evaluar aumentar +**Estado:** badge implementado en Etapa 9 con 14×14px. Director validó +visualmente y comentó "podría ser un poquito más grande". +**Acción:** evaluar en Sprint 2 si subir a 16×16px o 18×18px. Verificar +que no entre en conflicto con bordes de nodos chicos del BPMN. + +### [INVESTIGATING] Toggle automatable + Guardar requerido para badge +**Estado:** comportamiento intencional. Switch del ActivityPanel cambia +visualmente, pero el badge en BpmnCanvas solo aparece después de "Guardar". +**Decisión actual (Sprint 1.5):** mantener como está. Es UX deliberada. +**Acción:** revisar en Sprint 2 con feedback real de uso en talleres. +Si genera confusión recurrente, evaluar Opción B (indicador visual de +"pendiente de guardar") o Opción C (auto-save). + +### [RESOLVED] Badge ⚡ naranja en BpmnCanvas — Etapa 9 +**Resultado:** badge rediseñado con identidad InQ, hex hardcodeados eliminados, 526 tests verdes. +**Sprint cerrado en:** Sprint 1.5 Etapa 9. + +### [RESOLVED] Refinamientos página 1 PDF ROI — Etapa 11 +**Resultado:** KPI Hero 26pt, banner con bold naranja oscuro, grid 2×2 uniforme 9/18/9pt, Top 3 con título 11pt. Esquinas redondeadas via canvas clip con fondo blanco opaco. +**Sprint cerrado en:** Sprint 1.5 Etapa 11. diff --git a/methodology/CASE_STUDIES/inq-roi-sprint-1-5.md b/methodology/CASE_STUDIES/inq-roi-sprint-1-5.md index af2e6d4..8b80c99 100644 --- a/methodology/CASE_STUDIES/inq-roi-sprint-1-5.md +++ b/methodology/CASE_STUDIES/inq-roi-sprint-1-5.md @@ -1,25 +1,25 @@ -# Caso de estudio: InQ ROI Sprint 1.5 +# Caso de estudio: InQ ROI — Sprint 1.5 -> Primer caso completo del método aplicado en producción. +> 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 + 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 +> **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 del sprint están versionados en el repo del producto: +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` -- **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__/` +- **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` --- @@ -27,64 +27,198 @@ Todos los artefactos del sprint están versionados en el repo del producto: 11 etapas en orden: -| # | Etapa | Estado | Patrón principal aplicado | +| # | Etapa | Resultado | Patrón principal | |---|---|---|---| -| 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 | | +| 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 | --- -## Lecciones documentadas +## Alcance del sprint — qué se construyó -### Patrones validados durante este caso +### 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) -[Se completa al cierre del sprint con la lista de patrones que se validaron en práctica] +### 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 -### Anti-patrones cazados durante este caso +### 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 -- **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 +- 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) --- -## Métricas finales del sprint +## Aplicación del método — patrones con casos concretos -[Completar al cierre] +### A.1 — Brief versionado en `sprints/sprint-N/BRIEF.md` -- 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] +**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. --- -## Reflexión final +## Anti-patrones detectados con casos concretos -[Completar al cierre del sprint con observaciones del director sobre qué funcionó, qué no, y qué cambiaríamos para el próximo proyecto] +### 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.