actualizada politica de toma de decisión

This commit is contained in:
2026-05-17 00:37:44 -03:00
parent 293c225819
commit 5ef385c4a3
8 changed files with 453 additions and 1 deletions

View File

@@ -293,4 +293,19 @@ Antes de presentar cualquier PDF al usuario, verificá que:
1. El header/footer dice "InQ ROI" (no "Process Cost Platform" ni otro)
2. El footer incluye "Powered by InQuality"
3. No hay caracteres rotos (símbolos sin renderizar)
4. La marca "InQ" se escribe siempre I-n-Q
4. La marca "InQ" se escribe siempre I-n-Q
---
## Política de iniciativa proactiva
Cuando detectés una oportunidad de mejora fuera del scope del prompt actual:
- Cambios triviales (variables internas, reordenar imports): ejecutar
- Cambios visibles pero reversibles (wording, spacing, tooltips):
ejecutar y reportar explícitamente al final
- Cambios de marca, arquitectura o datos (paleta, dependencias,
estructura, features nuevas): CONSULTAR ANTES DE PROCEDER
Ver methodology/PRINCIPLES.md sección "Política de iniciativa agéntica"
para detalle completo.

57
TODO.md
View File

@@ -47,3 +47,60 @@
- [ ] **Marketplace de procesos**: biblioteca de BPMNs precostos por industria
- [ ] **Elementos RPA y agentes**: soporte para costos de bots y workflows automatizados
- [ ] **Tutoriales interactivos**: onboarding guiado para usuarios nuevos
## Observaciones de Etapa 3 (Sprint 1.5) — pendientes de Sprint 3-4 o posterior
### 1. Footer "Hecho desde Paraguay 🇵🇾" — evaluar destino
**Estado:** mantenido en web app por decisión del director.
**Decisión pendiente:** ¿se mantiene en producción cuando InQuality eventualmente venda a clientes internacionales no-LATAM?
**Argumentos a favor:** identidad regional, toque humano, diferenciador respecto a herramientas anónimas, alineado con tendencia LATAM de productos open source ("Made in Argentina/Brasil/etc.").
**Argumentos en contra:** sesgo gringo en clientes corporativos puede leer la firma regional como debilidad de credibilidad.
**Acción:** evaluar en Sprint 3-4 con feedback de uso real en talleres y demos. Decisión depende del posicionamiento de mercado.
---
### 2. Versión "v0.1.0" en footer — eliminar de PDFs
**Estado:** aparece en footer web. Decisión: **mantener en web, sacar de PDF**.
**Justificación:** en web la versión es útil para el usuario interno (saber qué features tiene). En PDFs entregados al cliente, la versión puede generar dudas de estabilidad ("¿v0.1.0 es producción?").
**Acción:** en Etapa 4 (PDF: header y footer compartidos), no incluir versión en el footer del PDF. Documentar como decisión de diseño en CLAUDE.md o ARCHITECTURE.md.
---
### 3. CumulativeSavingsChart — empezar en `-inversión`, no en 0
**Estado:** actualmente el gráfico parte de `(Año 0, 0)`. Decisión: cambiar a `(Año 0, -inversión)` para ser financieramente honesto.
**Justificación:** el modelo actual muestra ahorro bruto acumulado, no neto. Mostrar el punto inicial como `-USD 80.000` (la inversión) hace visible el "valle de retorno": la línea cruza el cero exactamente en el mes de payback. Es la representación estándar en análisis financiero.
**Impacto:**
- Cambio en `src/features/report/CumulativeSavingsChart.tsx` (web)
- Cambio en `src/lib/export/pdf-sections-roi.ts` cuando se rediseñe el chart en Etapa 6 (PDF)
- Aplicar consistente en ambas vistas
**Acción:** incorporar en roadmap de Etapa siguiente del Sprint 1.5 (probablemente Etapa 6 cuando se rediseñe la página 1 del PDF ROI). Si Etapa 6 ya tiene scope cerrado, mover a Sprint 2.
---
### 4. Label "Payback" superpuesto con eje Y en CumulativeSavingsChart
**Estado:** bug visual menor. El texto del marker vertical "Payback · X meses" se superpone con los labels del eje Y (`0.0M`, `2.0M`, etc.).
**Acción:** ajustar offset del label del marker payback en `CumulativeSavingsChart.tsx`. Trabajo de 10 min en próxima etapa que toque el componente.
**Prioridad:** baja. No afecta funcionalidad, solo polish visual.
---
### Notas operativas
- Las 4 observaciones se descubrieron en validación visual del director (no en tests ni reporte automático).
- Refuerzan el valor del **Patrón C.1** (validación visual mandatoria del artefacto final).
- Punto 1 dio origen al **Patrón C.6** documentado en `methodology/` (iniciativa agéntica con consulta).

BIN
etapa-3-cosecha.tar.gz Normal file

Binary file not shown.

View File

@@ -0,0 +1,45 @@
# Snippet de actualización para `methodology/PATTERNS.md`
> Este patch agrega el patrón **C.6** después del patrón **C.5**.
---
## Acción: agregar al final de la **Categoría C — Validación de output**
Después del patrón **C.5** (Validaciones programáticas explícitas), agregar:
---
### C.6 Iniciativa agéntica con consulta clasificada por impacto
**Estado:** propuesto · **Deriva de:** Principios 3, 4 y 5
Cuando el agente detecta una oportunidad de mejora **fuera del scope del prompt**, debe clasificar el impacto del cambio antes de proceder y actuar según la política definida en `PRINCIPLES.md` sección "Política de iniciativa agéntica".
**Niveles de impacto:**
1. **Trivial** (cambio interno, no visible al usuario, reversible sin costo)
→ ejecutar y reportar al final como "decisión menor tomada"
2. **Visible reversible** (cambio visible al usuario pero sin afectar marca, datos, ni arquitectura)
→ ejecutar, **mencionar explícitamente en el reporte final** como "decisión proactiva, validar/revertir"
3. **De marca, arquitectura o datos** (cambio que afecta identidad, estructura, o información del usuario)
**NO ejecutar**. Consultar antes de proceder.
**Por qué:** los agentes producen mejor cuando tienen libertad para optimizar lo local. Pero esa libertad sin límites lleva a cambios silenciosos que el humano descubre por casualidad. Una clasificación explícita preserva la velocidad agéntica sin perder gobernanza.
**Caso real:** InQ ROI Sprint 1.5 Etapa 3. Claude Code agregó "Hecho desde Paraguay 🇵🇾" al footer del web app sin estar en el brief. El cambio era razonable, alineado con identidad de marca, pero **el humano lo descubrió revisando screenshots**, no porque se reportara. Decisión retroactiva: mantener, pero documentar el patrón para que en el futuro este tipo de cambios (impacto nivel 3, afecta marca) sean consulta previa, no decisión unilateral.
**Indicador de aplicación correcta:**
- El reporte final del agente tiene una sección explícita "Decisiones tomadas por iniciativa" listando cambios fuera del scope
- Los cambios nivel 3 no se ejecutan sin consulta previa documentada
- El humano puede aprobar o revertir cambios nivel 2 sin tener que reconstruir contexto
**Indicador de violación:**
- Descubrir cambios en el output que no están ni en el prompt ni en el reporte
- Cambios de marca, arquitectura o datos ejecutados sin consulta previa
- "Pequeñas mejoras de UX" agregadas en silencio que cambian el comportamiento del producto
**Relación con otros patrones:**
- 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.

View File

@@ -0,0 +1,135 @@
# Snippet de actualización para `methodology/PRINCIPLES.md`
> Este patch agrega una nueva sección al final del archivo, después del Principio 5
> y de las relaciones entre principios.
---
## Acción: agregar al final del archivo, como sección complementaria
Después de la sección "Cómo se relacionan los 5 principios", agregar:
---
# Política de iniciativa agéntica
> Política operativa que define cuándo un agente puede actuar proactivamente y cuándo debe consultar antes. Complementa el Principio 5 (humano como director).
## El problema que resuelve
Los agentes producen mejor con libertad para optimizar lo local. Pero libertad sin límites lleva a:
- Cambios silenciosos que el humano descubre por casualidad
- Pérdida de gobernanza sobre el producto
- Erosión de la marca, arquitectura, o datos sin que nadie lo decida explícitamente
La política clasifica los cambios proactivos por impacto y define el comportamiento esperado en cada nivel.
## Clasificación de impacto
### Nivel 1 — Trivial
**Definición:** cambio interno no visible al usuario, reversible sin costo, sin efecto en datos o arquitectura.
**Ejemplos:**
- Renombrar una variable interna por claridad
- Reordenar imports
- Mejorar legibilidad de un comentario
- Extraer una función helper si se usa 3+ veces
**Política:** ejecutar libremente. Mencionar al final del reporte solo si fueron varios cambios acumulados.
### Nivel 2 — Visible reversible
**Definición:** cambio visible al usuario final pero sin afectar marca, datos, ni arquitectura. Reversión cuesta minutos, no horas.
**Ejemplos:**
- Mejorar wording de un mensaje de error
- Ajustar padding o spacing en un componente
- Agregar un tooltip explicativo donde falta
- Reordenar columnas de una tabla para mejor lectura
**Política:** ejecutar **y mencionar explícitamente en el reporte final** como "decisión proactiva tomada — validar/revertir". El humano puede aprobar retroactivamente o pedir reversión.
### Nivel 3 — De marca, arquitectura o datos
**Definición:** cambio que afecta identidad de marca, estructura del sistema, o información del usuario. Reversión cuesta horas o más.
**Ejemplos:**
- Agregar texto de marca al footer (ej. "Hecho desde Paraguay 🇵🇾")
- Cambiar colores que afectan la paleta visual del producto
- Agregar nuevas dependencias (npm packages, fonts, libs)
- Modificar estructura de datos persistidos (DB, IndexedDB)
- Cambiar flujos de navegación o jerarquía de información
- Agregar/quitar features no listadas en el brief
**Política:** **NO ejecutar.** Consultar antes de proceder. El reporte debe incluir:
```
PROPUESTA DE CAMBIO NIVEL 3 — requiere aprobación antes de implementar
Cambio sugerido: [descripción]
Justificación: [por qué el agente lo considera valioso]
Impacto: [qué afecta]
Alternativa si se rechaza: [qué hacer en lugar]
```
El humano decide explícitamente si proceder.
## Casos límite
### "Es trivial técnicamente pero visible para el usuario"
Sube a Nivel 2. La visibilidad es el criterio dominante.
### "El brief no lo prohíbe explícitamente"
Irrelevante. El brief define el scope positivo (qué hacer), no negativo (todo lo demás). Cualquier cambio fuera del scope explícito se clasifica por impacto y se aplica la política.
### "El cliente / usuario lo va a agradecer"
No es justificación para Nivel 3. La gratitud retroactiva no compensa el costo de la decisión unilateral. Si el cambio es bueno, sobrevive a la consulta previa.
### "Es para arreglar un bug que descubrí"
Bugs reales se arreglan. Pero **bugs cosméticos o de UX** suelen ser Nivel 2 y se reportan, no se silencian. Bugs de datos o seguridad son Nivel 3 y se consultan si requieren cambio de modelo.
## Cómo se aplica esta política en la práctica
### Para el agente
Antes de hacer un cambio fuera del scope explícito del prompt:
1. ¿Es trivial? → ejecutar
2. ¿Es visible pero reversible? → ejecutar y reportar explícitamente
3. ¿Afecta marca, arquitectura, datos? → consultar primero
### Para el humano
Al revisar un reporte:
1. Buscar la sección "Decisiones tomadas por iniciativa"
2. Validar cada cambio Nivel 2 (aprobar o pedir reversión)
3. Si hay propuesta Nivel 3, decidir antes de aprobar la etapa
4. Si descubrís un cambio no reportado, **es violación del patrón C.6** — registrar y discutir
### Para el método
Esta política es **viva**. Si en práctica aparecen casos que no encajan claramente en los 3 niveles, documentar el caso y refinar la política. La política es herramienta, no dogma.
---
## Cómo se relaciona con los 5 principios
- **Principio 3 (Auditoría adversarial):** la política le da al humano una sección concreta donde buscar cambios silenciosos.
- **Principio 4 (Decisiones como contratos):** los cambios Nivel 3 generan nuevas decisiones que se registran formalmente.
- **Principio 5 (Humano director, no operador):** la política preserva la autonomía agéntica útil sin perder gobernanza sobre el producto.
---
## Aplicación en CLAUDE.md del producto
Para que un agente conozca y aplique esta política, agregar en `CLAUDE.md` del producto:
```markdown
## Política de iniciativa proactiva
Cuando detectés una oportunidad de mejora fuera del scope del prompt actual:
- Cambios triviales (variables internas, reordenar imports): ejecutar
- Cambios visibles pero reversibles (wording, spacing, tooltips):
ejecutar y reportar explícitamente al final
- Cambios de marca, arquitectura o datos (paleta, dependencias,
estructura, features nuevas): CONSULTAR ANTES DE PROCEDER
Ver methodology/PRINCIPLES.md sección "Política de iniciativa agéntica"
para detalle completo.
```

View File

@@ -0,0 +1,62 @@
# Snippet para agregar a `TODO.md` del proyecto InQ ROI
> Agregá esta sección al `TODO.md` del repo del producto (no de methodology).
---
## Observaciones de Etapa 3 (Sprint 1.5) — pendientes de Sprint 3-4 o posterior
### 1. Footer "Hecho desde Paraguay 🇵🇾" — evaluar destino
**Estado:** mantenido en web app por decisión del director.
**Decisión pendiente:** ¿se mantiene en producción cuando InQuality eventualmente venda a clientes internacionales no-LATAM?
**Argumentos a favor:** identidad regional, toque humano, diferenciador respecto a herramientas anónimas, alineado con tendencia LATAM de productos open source ("Made in Argentina/Brasil/etc.").
**Argumentos en contra:** sesgo gringo en clientes corporativos puede leer la firma regional como debilidad de credibilidad.
**Acción:** evaluar en Sprint 3-4 con feedback de uso real en talleres y demos. Decisión depende del posicionamiento de mercado.
---
### 2. Versión "v0.1.0" en footer — eliminar de PDFs
**Estado:** aparece en footer web. Decisión: **mantener en web, sacar de PDF**.
**Justificación:** en web la versión es útil para el usuario interno (saber qué features tiene). En PDFs entregados al cliente, la versión puede generar dudas de estabilidad ("¿v0.1.0 es producción?").
**Acción:** en Etapa 4 (PDF: header y footer compartidos), no incluir versión en el footer del PDF. Documentar como decisión de diseño en CLAUDE.md o ARCHITECTURE.md.
---
### 3. CumulativeSavingsChart — empezar en `-inversión`, no en 0
**Estado:** actualmente el gráfico parte de `(Año 0, 0)`. Decisión: cambiar a `(Año 0, -inversión)` para ser financieramente honesto.
**Justificación:** el modelo actual muestra ahorro bruto acumulado, no neto. Mostrar el punto inicial como `-USD 80.000` (la inversión) hace visible el "valle de retorno": la línea cruza el cero exactamente en el mes de payback. Es la representación estándar en análisis financiero.
**Impacto:**
- Cambio en `src/features/report/CumulativeSavingsChart.tsx` (web)
- Cambio en `src/lib/export/pdf-sections-roi.ts` cuando se rediseñe el chart en Etapa 6 (PDF)
- Aplicar consistente en ambas vistas
**Acción:** incorporar en roadmap de Etapa siguiente del Sprint 1.5 (probablemente Etapa 6 cuando se rediseñe la página 1 del PDF ROI). Si Etapa 6 ya tiene scope cerrado, mover a Sprint 2.
---
### 4. Label "Payback" superpuesto con eje Y en CumulativeSavingsChart
**Estado:** bug visual menor. El texto del marker vertical "Payback · X meses" se superpone con los labels del eje Y (`0.0M`, `2.0M`, etc.).
**Acción:** ajustar offset del label del marker payback en `CumulativeSavingsChart.tsx`. Trabajo de 10 min en próxima etapa que toque el componente.
**Prioridad:** baja. No afecta funcionalidad, solo polish visual.
---
### Notas operativas
- Las 4 observaciones se descubrieron en validación visual del director (no en tests ni reporte automático).
- Refuerzan el valor del **Patrón C.1** (validación visual mandatoria del artefacto final).
- Punto 1 dio origen al **Patrón C.6** documentado en `methodology/` (iniciativa agéntica con consulta).

View File

@@ -206,6 +206,40 @@ Build:
- No reemplaza **C.1** (validación visual humana) — son complementarias
- Es Fase 2 del roadmap de `AUTOMATION_STRATEGY.md`
### C.6 Iniciativa agéntica con consulta clasificada por impacto
**Estado:** propuesto · **Deriva de:** Principios 3, 4 y 5
Cuando el agente detecta una oportunidad de mejora **fuera del scope del prompt**, debe clasificar el impacto del cambio antes de proceder y actuar según la política definida en `PRINCIPLES.md` sección "Política de iniciativa agéntica".
**Niveles de impacto:**
1. **Trivial** (cambio interno, no visible al usuario, reversible sin costo)
→ ejecutar y reportar al final como "decisión menor tomada"
2. **Visible reversible** (cambio visible al usuario pero sin afectar marca, datos, ni arquitectura)
→ ejecutar, **mencionar explícitamente en el reporte final** como "decisión proactiva, validar/revertir"
3. **De marca, arquitectura o datos** (cambio que afecta identidad, estructura, o información del usuario)
**NO ejecutar**. Consultar antes de proceder.
**Por qué:** los agentes producen mejor cuando tienen libertad para optimizar lo local. Pero esa libertad sin límites lleva a cambios silenciosos que el humano descubre por casualidad. Una clasificación explícita preserva la velocidad agéntica sin perder gobernanza.
**Caso real:** InQ ROI Sprint 1.5 Etapa 3. Claude Code agregó "Hecho desde Paraguay 🇵🇾" al footer del web app sin estar en el brief. El cambio era razonable, alineado con identidad de marca, pero **el humano lo descubrió revisando screenshots**, no porque se reportara. Decisión retroactiva: mantener, pero documentar el patrón para que en el futuro este tipo de cambios (impacto nivel 3, afecta marca) sean consulta previa, no decisión unilateral.
**Indicador de aplicación correcta:**
- El reporte final del agente tiene una sección explícita "Decisiones tomadas por iniciativa" listando cambios fuera del scope
- Los cambios nivel 3 no se ejecutan sin consulta previa documentada
- El humano puede aprobar o revertir cambios nivel 2 sin tener que reconstruir contexto
**Indicador de violación:**
- Descubrir cambios en el output que no están ni en el prompt ni en el reporte
- Cambios de marca, arquitectura o datos ejecutados sin consulta previa
- "Pequeñas mejoras de UX" agregadas en silencio que cambian el comportamiento del producto
**Relación con otros patrones:**
- 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.
---
## Categoría D — Estructura del repo

View File

@@ -118,3 +118,107 @@ desde validación humana 100% hasta pipeline multi-agente).
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).
---
# Política de iniciativa agéntica
> Política operativa que define cuándo un agente puede actuar proactivamente y cuándo debe consultar antes. Complementa el Principio 5 (humano como director).
## El problema que resuelve
Los agentes producen mejor con libertad para optimizar lo local. Pero libertad sin límites lleva a:
- Cambios silenciosos que el humano descubre por casualidad
- Pérdida de gobernanza sobre el producto
- Erosión de la marca, arquitectura, o datos sin que nadie lo decida explícitamente
La política clasifica los cambios proactivos por impacto y define el comportamiento esperado en cada nivel.
## Clasificación de impacto
### Nivel 1 — Trivial
**Definición:** cambio interno no visible al usuario, reversible sin costo, sin efecto en datos o arquitectura.
**Ejemplos:**
- Renombrar una variable interna por claridad
- Reordenar imports
- Mejorar legibilidad de un comentario
- Extraer una función helper si se usa 3+ veces
**Política:** ejecutar libremente. Mencionar al final del reporte solo si fueron varios cambios acumulados.
### Nivel 2 — Visible reversible
**Definición:** cambio visible al usuario final pero sin afectar marca, datos, ni arquitectura. Reversión cuesta minutos, no horas.
**Ejemplos:**
- Mejorar wording de un mensaje de error
- Ajustar padding o spacing en un componente
- Agregar un tooltip explicativo donde falta
- Reordenar columnas de una tabla para mejor lectura
**Política:** ejecutar **y mencionar explícitamente en el reporte final** como "decisión proactiva tomada — validar/revertir". El humano puede aprobar retroactivamente o pedir reversión.
### Nivel 3 — De marca, arquitectura o datos
**Definición:** cambio que afecta identidad de marca, estructura del sistema, o información del usuario. Reversión cuesta horas o más.
**Ejemplos:**
- Agregar texto de marca al footer (ej. "Hecho desde Paraguay 🇵🇾")
- Cambiar colores que afectan la paleta visual del producto
- Agregar nuevas dependencias (npm packages, fonts, libs)
- Modificar estructura de datos persistidos (DB, IndexedDB)
- Cambiar flujos de navegación o jerarquía de información
- Agregar/quitar features no listadas en el brief
**Política:** **NO ejecutar.** Consultar antes de proceder. El reporte debe incluir:
```
PROPUESTA DE CAMBIO NIVEL 3 — requiere aprobación antes de implementar
Cambio sugerido: [descripción]
Justificación: [por qué el agente lo considera valioso]
Impacto: [qué afecta]
Alternativa si se rechaza: [qué hacer en lugar]
```
El humano decide explícitamente si proceder.
## Casos límite
### "Es trivial técnicamente pero visible para el usuario"
Sube a Nivel 2. La visibilidad es el criterio dominante.
### "El brief no lo prohíbe explícitamente"
Irrelevante. El brief define el scope positivo (qué hacer), no negativo (todo lo demás). Cualquier cambio fuera del scope explícito se clasifica por impacto y se aplica la política.
### "El cliente / usuario lo va a agradecer"
No es justificación para Nivel 3. La gratitud retroactiva no compensa el costo de la decisión unilateral. Si el cambio es bueno, sobrevive a la consulta previa.
### "Es para arreglar un bug que descubrí"
Bugs reales se arreglan. Pero **bugs cosméticos o de UX** suelen ser Nivel 2 y se reportan, no se silencian. Bugs de datos o seguridad son Nivel 3 y se consultan si requieren cambio de modelo.
## Cómo se aplica esta política en la práctica
### Para el agente
Antes de hacer un cambio fuera del scope explícito del prompt:
1. ¿Es trivial? → ejecutar
2. ¿Es visible pero reversible? → ejecutar y reportar explícitamente
3. ¿Afecta marca, arquitectura, datos? → consultar primero
### Para el humano
Al revisar un reporte:
1. Buscar la sección "Decisiones tomadas por iniciativa"
2. Validar cada cambio Nivel 2 (aprobar o pedir reversión)
3. Si hay propuesta Nivel 3, decidir antes de aprobar la etapa
4. Si descubrís un cambio no reportado, **es violación del patrón C.6** — registrar y discutir
### Para el método
Esta política es **viva**. Si en práctica aparecen casos que no encajan claramente en los 3 niveles, documentar el caso y refinar la política. La política es herramienta, no dogma.
---
## Cómo se relaciona con los 5 principios
- **Principio 3 (Auditoría adversarial):** la política le da al humano una sección concreta donde buscar cambios silenciosos.
- **Principio 4 (Decisiones como contratos):** los cambios Nivel 3 generan nuevas decisiones que se registran formalmente.
- **Principio 5 (Humano director, no operador):** la política preserva la autonomía agéntica útil sin perder gobernanza sobre el producto.