From 5ef385c4a3544e7e7c29a78152368662e88dd059 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcos=20Ben=C3=ADtez?= Date: Sun, 17 May 2026 00:37:44 -0300 Subject: [PATCH] =?UTF-8?q?actualizada=20politica=20de=20toma=20de=20decis?= =?UTF-8?q?i=C3=B3n?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 17 ++- TODO.md | 57 ++++++++ etapa-3-cosecha.tar.gz | Bin 0 -> 4863 bytes etapa-3-cosecha/PATTERNS_C6_PATCH.md | 45 ++++++ .../PRINCIPLES_INICIATIVA_PATCH.md | 135 ++++++++++++++++++ etapa-3-cosecha/TODO_PATCH.md | 62 ++++++++ methodology/PATTERNS.md | 34 +++++ methodology/PRINCIPLES.md | 104 ++++++++++++++ 8 files changed, 453 insertions(+), 1 deletion(-) create mode 100644 etapa-3-cosecha.tar.gz create mode 100644 etapa-3-cosecha/PATTERNS_C6_PATCH.md create mode 100644 etapa-3-cosecha/PRINCIPLES_INICIATIVA_PATCH.md create mode 100644 etapa-3-cosecha/TODO_PATCH.md diff --git a/CLAUDE.md b/CLAUDE.md index 08b1d10..9295781 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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 \ No newline at end of file +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. \ No newline at end of file diff --git a/TODO.md b/TODO.md index a4fc213..2c1b04f 100644 --- a/TODO.md +++ b/TODO.md @@ -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). \ No newline at end of file diff --git a/etapa-3-cosecha.tar.gz b/etapa-3-cosecha.tar.gz new file mode 100644 index 0000000000000000000000000000000000000000..6bee045b2ff0f79e6052b069a40cfbefe61f3dc0 GIT binary patch literal 4863 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 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. diff --git a/etapa-3-cosecha/PRINCIPLES_INICIATIVA_PATCH.md b/etapa-3-cosecha/PRINCIPLES_INICIATIVA_PATCH.md new file mode 100644 index 0000000..2b64b52 --- /dev/null +++ b/etapa-3-cosecha/PRINCIPLES_INICIATIVA_PATCH.md @@ -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. +``` diff --git a/etapa-3-cosecha/TODO_PATCH.md b/etapa-3-cosecha/TODO_PATCH.md new file mode 100644 index 0000000..8bd4348 --- /dev/null +++ b/etapa-3-cosecha/TODO_PATCH.md @@ -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). diff --git a/methodology/PATTERNS.md b/methodology/PATTERNS.md index e896ba7..07ca80b 100644 --- a/methodology/PATTERNS.md +++ b/methodology/PATTERNS.md @@ -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 diff --git a/methodology/PRINCIPLES.md b/methodology/PRINCIPLES.md index 2a8b2c0..1a24640 100644 --- a/methodology/PRINCIPLES.md +++ b/methodology/PRINCIPLES.md @@ -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.