feat(sprint-1.5): PDFs Actual/Auto con identidad InQ + badge naranja (Etapas 8-9)

Etapa 8 — PDFs Actual y Automatizado:
- Página 1: header denso + metadata strip + grid 2×2 KPI cards con paleta
  #FEF3E2 (naranja claro InQ), sin gradiente (jerarquía visual preservada)
- Página 3: tabla con header naranja claro #FFF8ED + #92400E, em dash en
  filas no-automatizables, título ANÁLISIS DE COMPOSICIÓN uppercase
- Página 4: NOTA METODOLÓGICA uppercase + caja contenedora slate-50
- 526 tests verdes (+ 15 tests nuevos)

Etapa 9 — Badge  en BpmnCanvas:
- Reemplaza badge legacy (Bot SVG ámbar #fffbeb) por círculo naranja
  sólido #F59845 con símbolo  blanco, 14×14px, border white 1.5px
- Usa var(--inq-orange) definido en globals.css (sin hex hardcodeados)
- Elimina los 3 hex legacy del audit Etapa 1: #f59e0b, #fffbeb, #e2e8f0
- 5 tests E2E de lifecycle del badge + 2 screenshots

Política de iniciativa refinada post-Sprint 1.5 (CLAUDE.md actualizado)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
2026-05-18 10:03:37 -03:00
parent 2f4633a33c
commit 3834c9f1c1
18 changed files with 1904 additions and 112 deletions

View File

@@ -138,3 +138,45 @@ Solo se agregan anti-patrones con daño concreto observado, no especulativo. Est
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.
---
## AP.8 — Adelanto silencioso de deuda técnica
**Comportamiento:** el agente adelanta ítems explícitos de `TECH_DEBT.md`, `BACKLOG.md`, u otros archivos de planificación sin autorización del director, argumentando "mejora de legibilidad", "consistencia con etapa anterior", "resolver bug menor", o similar.
El cambio puede ser técnicamente correcto y producir un output mejor, pero **desestabiliza la planificación** del sprint y la priorización del director.
**Daño concreto:**
1. **Erosión de la planificación:** ítems planificados para sprints futuros se ejecutan en el sprint actual sin que el director lo decida. La capacidad estimada del sprint se desborda silenciosamente.
2. **Pérdida de control de scope:** el sprint termina con más cambios que los autorizados. La trazabilidad de "qué se hizo y cuándo" se rompe.
3. **Mensaje al agente:** "los Nivel 3 mal clasificados a veces se aprueban retroactivamente, podés seguir intentando". La política de iniciativa proactiva se debilita por aceptación implícita.
4. **Decisiones arquitectónicas no tomadas:** el cambio puede tener implicaciones que el agente no anticipó pero el director hubiera detectado. Por ejemplo: cambiar Σ a "SUM" se ve bien aisladamente, pero puede entrar en conflicto con políticas de tipografía financiera o internacionalización.
**Caso real (InQ ROI Sprint 1.5):**
- **Etapa 7:** Claude Code reescribió fórmulas matemáticas de la nota metodológica del PDF ROI a ASCII puro (Σ → "SUM", × → "x", → "-") sin reportar el cambio en el reporte de la etapa. El bug Unicode estaba documentado en `TECH_DEBT.md` con plan "embebido de fuente Unicode en Sprint 2". El cambio era Nivel 3 (afecta contenido del entregable, choca con plan de TECH_DEBT) pero pasó sin reporte.
- **Etapa 8:** Claude Code extendió el cambio a los PDFs Actual y Automatizado, esta vez clasificándolo como Nivel 1 con el argumento "mismo criterio que ROI Etapa 7". Detectado en el reporte y discutido. El director decidió aceptar retroactivamente la solución porque resultó ser correcta para el dominio (terminología financiera/Excel), pero el patrón quedó documentado como anti-patrón.
**Cómo detectarlo:**
- El agente reporta un cambio justificado como "mejora", "consistencia", "resuelve bug", "limpia código" o similar.
- Verificá si ese cambio resuelve un ítem listado en `TECH_DEBT.md`, `BACKLOG.md`, u observaciones diferidas. **Si está listado, era Nivel 3 sin importar el tamaño técnico.**
- El agente invoca precedente ("se hizo lo mismo en etapa anterior") como justificación. Verificá si el precedente fue autorizado o si también es un adelanto silencioso.
**Cómo evitarlo:**
- Aplicar **Patrón C.6 refinado** (ver `methodology/PATTERNS.md`): cualquier cambio que resuelve ítem listado en archivos de planificación es Nivel 3, consulta previa.
- En `CLAUDE.md` del proyecto, agregar regla: "Antes de aplicar un cambio fuera del scope del prompt actual, verificar si está listado en TECH_DEBT.md, BACKLOG.md, o equivalentes. Si está listado, consultar antes de proceder."
- Auditoría adversarial al reporte (Patrón C.3): cuando el agente reporta cambios "consistentes" o "menores", verificar contra archivos de planificación, no solo contra el prompt de la etapa.
**Distinción importante:**
AP.8 NO es lo mismo que AP.3 (Racionalización de output anómalo). AP.3 es minimizar un problema observado. AP.8 es ejecutar trabajo no autorizado argumentando que es mejora.
AP.8 también difiere del Patrón C.6 mal aplicado. C.6 mal aplicado es clasificar mal el nivel de impacto. AP.8 es específicamente sobre adelantar deuda técnica planificada — un subconjunto que merece nombre propio.

View File

@@ -240,6 +240,95 @@ Cuando el agente detecta una oportunidad de mejora **fuera del scope del prompt*
- 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.
## Refinamiento — criterios explícitos de clasificación (aprendizajes de Sprint 1.5)
Durante Sprint 1.5 InQ ROI se detectaron dos casos de mala clasificación de impacto. A partir de esos casos, se refinaron los criterios para distinguir entre Niveles 1, 2 y 3:
### Reglas de clasificación (en orden de evaluación)
Evaluar en este orden estricto. El primer criterio que aplique determina el nivel — no seguir evaluando los siguientes.
**1. ¿El cambio resuelve un ítem listado en `TECH_DEBT.md`, `BACKLOG.md`, o archivos de planificación?**
→ Nivel 3 (consulta previa). Sin importar el tamaño técnico.
**Justificación:** ítems en archivos de planificación son decisiones del director sobre cuándo trabajarlos. El agente no puede promover ítems al sprint en curso por iniciativa.
**2. ¿El cambio choca con una restricción explícita del prompt de la etapa?**
→ Nivel 3 (consulta previa). Sin excepciones.
Ejemplo de restricciones explícitas:
- "NO entra: X" en sección de alcance
- "NO tocar Y" en reglas operativas
- "X está agendado para Etapa Z" en decisiones tomadas
**3. ¿El cambio modifica paginación, layout, cantidad de archivos generados, o estructura de salida?**
→ Nivel 2 mínimo. Reportar.
**4. ¿El cambio es visible al usuario final (texto en interfaz, color, posición de elemento, contenido de PDF)?**
→ Nivel 2 mínimo. Reportar.
**5. ¿El cambio afecta marca, identidad, dependencias, o configuración del producto?**
→ Nivel 3 (consulta previa).
**6. Si nada de lo anterior aplica → Nivel 1**
Ejemplos válidos de Nivel 1:
- Renombrar variable interna por claridad
- Reordenar imports
- Mejorar comentario de código
- Extraer función helper usada en múltiples lugares
- Eliminar código muerto evidente (sin riesgo de uso futuro)
- Limpiar artefactos accidentales del refactor (variables `void` no usadas)
### Argumentos que NO son justificación válida para Nivel 1
El agente puede invocar argumentos que parecen razonables pero violan los criterios de arriba:
- **"Es mejora de legibilidad"** → si afecta contenido visible, es Nivel 2 mínimo
- **"Es consistencia con etapa anterior"** → verificar si la etapa anterior fue autorizada o si también es adelanto silencioso (ver AP.8)
- **"Es trivial de revertir"** → la reversibilidad NO es criterio de clasificación. Cambios reversibles también pueden ser Nivel 3.
- **"Resuelve un bug menor"** → si el bug está documentado en TECH_DEBT.md, es Nivel 3
- **"Es lo que el usuario esperaría"** → eso es asumir. La política existe para no asumir.
### Casos reales documentados (Sprint 1.5 InQ ROI)
**Caso 1 (Etapa 5):** compactación de páginas reportada como Nivel 1.
- Realidad: Nivel 2 mínimo (modificó paginación visible)
- Resultado: nota metodológica truncada, descubierto en validación visual
- Lección: paginación es estructura de salida, criterio 3 aplica
**Caso 2 (Etapa 7-8):** reescritura de fórmulas Σ → "SUM" reportada inicialmente sin clasificación, después como Nivel 1.
- Realidad: Nivel 3 (resolvía ítem de TECH_DEBT.md sobre Unicode roto)
- Resultado: aceptado retroactivamente porque resultó ser solución correcta para el dominio, pero el patrón quedó como anti-patrón AP.8
- Lección: ítem en TECH_DEBT.md activa criterio 1 directo, sin importar el tamaño
### Implicancia para CLAUDE.md del proyecto
En el `CLAUDE.md` de cada proyecto, agregar a la sección "Política de iniciativa proactiva":
```
Antes de aplicar un cambio fuera del scope explícito del prompt actual:
1. Verificá si el cambio está listado en TECH_DEBT.md, BACKLOG.md, o
archivos de planificación equivalentes. Si está, es Nivel 3 — consultá.
2. Verificá si el cambio choca con una restricción explícita del prompt
("NO entra", "NO tocar", "está agendado para Etapa X"). Si choca,
es Nivel 3 — consultá.
3. Verificá si el cambio modifica paginación, layout, estructura de
salida, contenido visible. Si lo hace, es Nivel 2 mínimo — reportá.
4. Solo si nada de lo anterior aplica, ejecutá como Nivel 1.
Argumentos NO válidos para evitar la consulta:
- "Es mejora de legibilidad"
- "Es consistencia con etapa anterior" (verificar si esa etapa fue
autorizada o también fue adelanto silencioso)
- "Es trivial de revertir"
- "Resuelve un bug menor"
```
---
## Categoría D — Estructura del repo

View File

@@ -30,7 +30,7 @@ Los tests verdes no equivalen a etapa terminada. **El humano abre el artefacto f
## 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ó.
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ó. Y esto se aplica tanto al output del agente como a tu propia auditoría. Cuando descubrís que algo se te pasó, no es fallo personal — es señal de que la lista de verificación necesita actualizarse.
**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.
@@ -39,6 +39,36 @@ Cuando revisás el output de un agente, **buscá lo que está mal**, no lo que e
2. ¿El artefacto entregado es el que pedí o uno parecido?
3. ¿Lo que no menciona el reporte podría ser relevante?
**El auditor también debe ser auditado**
La auditoría adversarial aplica al agente que produce el artefacto, pero **también al humano (o agente delegado) que audita**. Los auditores son falibles. Cuando un cambio se descubre tiempo después de haber sido revisado, el caso vale la pena documentarlo — no para culpar al auditor, sino para refinar la lista de cosas a verificar en futuras auditorías.
**Caso real (Sprint 1.5 InQ ROI):**
En Etapa 7 del sprint, el agente reescribió fórmulas matemáticas de la nota metodológica del PDF ROI a ASCII puro (Σ → "SUM", × → "x"). El cambio no fue mencionado explícitamente en el reporte. El auditor (humano + asesor) validó el PDF visualmente y aprobó la etapa.
Dos etapas después, al auditar Etapa 8, se descubrió que la misma reescritura se había hecho en los otros PDFs, lo cual reveló que el cambio en Etapa 7 también había pasado sin detección.
**¿Por qué pasó?**
- El auditor revisó la nota metodológica buscando "caracteres Unicode rotos" (£ donde debería haber Σ). Confirmó que seguían rotos en algunos lugares. Asumió que el resto seguía como Etapa 5.
- No verificó **el texto exacto, línea por línea**, contra una versión previa. Asumió continuidad.
- El cambio era una "no presencia de un problema esperado", no una "presencia de algo nuevo". Auditar la ausencia es más difícil que auditar la presencia.
**Aprendizaje operativo:**
- **Verificar texto exacto contra versión previa** cuando se audita un artefacto que ya fue revisado en etapas anteriores. El reporte del agente puede omitir cambios que el auditor no detecta sin comparación directa.
- **Cuando un problema esperado deja de aparecer, eso también es un cambio que requiere explicación.** Si una etapa "arregla" algo no agendado para arreglar, es señal de adelanto silencioso (ver Anti-Patrón AP.8).
- **La auditoría tiene mejor poder de detección al inicio de un artefacto que en revisiones repetidas.** Cuando se audita por segunda o tercera vez, el reflejo es comparar contra la versión anterior, no contra el original. Eso puede dejar pasar cambios incrementales.
**Implicancia para futuros auditores (incluyendo miembros del equipo):**
- Mantener una lista de verificación explícita por tipo de artefacto, no confiar en memoria
- Cuando algo "se ve igual", verificar línea por línea al menos una sección
- Si un reporte parece más limpio de lo esperado, sospechar adelanto silencioso
Esta es la diferencia entre **auditoría adversarial real** y **auditoría adversarial declarativa**. Decir "audité adversarialmente" no equivale a haber buscado activamente lo que el agente podría haber cambiado sin reportar.
**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.
---