@saulwade/swl-ses 1.6.1 → 1.6.3

package/habilidades/proceso-intent-engineering/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: proceso-intent-engineering
+description: >
+  Framework "Intent Engineering" de 8 partes (Pawel Huryn, 2024-2026) para
+  especificar agentes IA: Strategy, Objective, Desired Outcomes, Health Metrics,
+  Org Context, Constraints (steering+hardGuardrails), Autonomy Boundaries, Stop
+  Rules. Cargar cuando se cree un agente nuevo nivelRiesgo:ALTO, se audite uno
+  existente, o se diagnostique un agente que falla por intent incompleto.
+when_to_use: >
+  Usar cuando el usuario menciona crear agente nuevo, refactor de agente ALTO,
+  promover MEDIO a ALTO, agente que "se desvia del objetivo", agente que ignora
+  restricciones blandas, intent spec, /goal, agentes que fallan por instrucciones
+  ambiguas, health metrics, steering vs guardrails.
+---
+
+# Intent Engineering — el framework de 8 partes para agentes
+
+## Cuándo cargar
+
+- Diseñar un agente nuevo `nivelRiesgo: ALTO` (uso obligatorio según
+  `reglas/intent-engineering.md`).
+- Refactorizar un agente existente que falla por intent ambiguo.
+- Auditar un agente con `/swl:revisar` y se detecta "deriva de scope".
+- Decidir cómo materializar restricciones blandas (steering) vs duras
+  (hardGuardrails) en un agente.
+- Promover un agente de `MEDIO` a `ALTO` — la regla exige las 8 partes.
+
+## Cuándo NO cargar
+
+- Agente `BAJO` o `MEDIO` riesgo — declarar las 8 partes es overkill.
+- Fix puntual de typo o ajuste de descripción de un agente existente.
+- Crear skill (no agente) — el framework aplica a agentes, no a skills.
+- Investigación de tooling externo (carga `investigador-swl`).
+
+## Fuente y verificación
+
+Adaptado de Pawel Huryn, *"Lead Agents Like Humans"* (Product Compass,
+2026-05). La cita clave que justifica las 8 partes:
+
+> "Lead agents the way good orgs lead empowered teams. OKRs (2016) →
+> empowered teams (2020) → intent engineering (2024). /goal is two of
+> eight parts." (Huryn, línea 5)
+
+`/goal` (slash command de Codex y Claude Code) cubre las partes 2 y 3.
+Las otras seis son responsabilidad del autor del agente.
+
+## Las 8 partes — qué declarar y dónde vive en SWL
+
+### Parte 1 — Strategy
+
+Visión, mercado, propuesta de valor, tradeoffs. Huryn lo describe así:
+
+> "You wouldn't onboard a senior PM with 'handle customer support.' You'd
+> ground them in the strategy first: vision, market, value proposition,
+> trade-offs." (línea 43)
+
+**Dónde vive en SWL**: frontmatter `strategy: "..."` (máx 500 chars).
+Cuando un agente operativo (`backend-python-swl`, `frontend-react-swl`)
+necesita strategy específica al proyecto, hereda del `CLAUDE.md`. Cuando
+el rol del agente impone trade-offs propios (`producto-prd-swl`,
+`arquitecto-swl`), se declara explícito.
+
+Ejemplo (`arquitecto-swl`):
+```yaml
+strategy: >
+  Diseñar para evolvabilidad sobre completitud inicial. Módulos profundos
+  (Ousterhout) sobre micro-servicios prematuros. ADRs sobre wikis. Reversible
+  sobre óptimo cuando el costo de equivocarse es bajo.
+```
+
+### Parte 2 — Objective
+
+El problema y por qué importa. Guía el juicio cuando las instrucciones se
+agotan.
+
+**Dónde vive en SWL**: campo `description:` del agente. Ya obligatorio
+por schema. Para captura la regla "qué hace + cuándo invocarlo".
+
+### Parte 3 — Desired Outcomes
+
+Estados observables (no actividades) que prueban el objetivo cumplido.
+Huryn enumera 4 reglas:
+
+- Observable states, not agent activities.
+- From the user's perspective, not the agent's.
+- Measurable or verifiable without relying on agent self-report.
+- Leading, not lagging.
+
+**Dónde vive en SWL**: criterios de aceptación en `PLAN.md` por feature.
+El `/swl:verificar` con goal-backward valida outcomes en 4 niveles.
+
+### Parte 4 — Health Metrics
+
+Lo que NO debe degradar mientras se persiguen outcomes. Cita textual:
+
+> "Goodhart's Law: when a measure becomes a target, it stops being a good
+> measure. [...] Health metrics steer; guardrails enforce." (líneas 134, 150)
+
+**Dónde vive en SWL**: frontmatter `healthMetrics: [...]`. Diferencia
+clave con outcomes: outcomes son lo que persigues; health metrics son lo
+que proteges mientras persigues.
+
+Ejemplo (`migrador-swl`):
+```yaml
+healthMetrics:
+  - Integridad referencial de datos durante toda la ventana de migración
+  - Tiempo de downtime <= 0 (expand-contract obligatorio)
+  - Tests preexistentes verde antes y después
+  - Sin warnings nuevos de ORM (N+1, lazy loading)
+```
+
+Si el agente detecta que una health metric está cayendo, **debe ser más
+conservador, no más agresivo** — esa es la diferencia operacional con un
+outcome.
+
+### Parte 5 — Org Context
+
+Sistema (otros agentes, hooks, tooling) + organización (proyecto, usuario,
+dominio). No todo va en el prompt:
+
+> "Core context (always needed) goes in the system prompt. Reference
+> context goes in retrieval. Dynamic context (per-request) goes in the
+> orchestration layer." (línea 159, parafraseada)
+
+**Dónde vive en SWL**: `CLAUDE.md` del proyecto (org), `contextos/`
+(dev/review/research), `INVENTARIO.md` (system context). El agente no
+necesita declararlo — lo recibe vía carga inicial.
+
+### Parte 6 — Constraints (los dos tipos)
+
+Huryn separa muy claramente:
+
+**Steering prompts (prompt-level)** — texto que el agente lee y debería
+seguir, pero puede ignorar bajo presión:
+- Behavioral guidance
+- Risk preferences
+- Tone and caution
+
+**Hard guardrails (orchestration-level)** — restricciones aplicadas en
+arquitectura, no en lenguaje:
+- Tool restrictions
+- Output validation
+- Action gating
+- Approval gates (HITL)
+
+> "If a constraint matters, it must be enforced in architecture, not
+> language. [...] The reasoning layer proposes. The orchestration layer
+> enforces. If a constraint lives only in the prompt, it's a suggestion."
+> (líneas 196, 197 paraf., 198)
+
+**Dónde vive en SWL**:
+- `steering: [...]` en frontmatter del agente (texto que el modelo lee)
+- `hardGuardrails: [...]` declara qué hook/regla/schema enforza qué
+  restricción. Sintaxis: `@reglas/X.md`, `@hooks/Y.js`, o texto inline
+  si es específico al agente.
+
+Anti-patrón: declarar como `steering` algo que necesita enforcement real
+("no eliminar archivos" sin hook que lo prevenga). Si la restricción
+importa, va en `hardGuardrails` con apoyo de hook/permiso/schema.
+
+### Parte 7 — Autonomy Boundaries
+
+Huryn define 4 niveles:
+
+1. **Full Autonomy** — acciones reversibles, impacto limitado, modos de
+   falla conocidos.
+2. **Guarded Autonomy** — cambios visibles al usuario, riesgo medio.
+   Requiere logging y rollback.
+3. **Proposal-First** — decisiones estratégicas. El agente propone, el
+   humano aprueba, el agente ejecuta.
+4. **No Autonomy (Human-Required)** — compromisos legales, cambios
+   irreversibles, acciones financieras.
+
+**Mapeo a SWL** (3 niveles, no 4 — decisión consciente, ver ADR-0025):
+
+| Huryn 4-tier | SWL `nivelRiesgo` | HITL? |
+|---|---|---|
+| Full Autonomy | BAJO | No |
+| Guarded Autonomy | MEDIO | Solo en ramas críticas |
+| Proposal-First | ALTO | Sí, antes de mutaciones irreversibles |
+| Human-Required | ALTO + `permisos*: false` | Sí, siempre |
+
+El nivel 4 de Huryn se modela en SWL como ALTO + permisos restrictivos en
+frontmatter. NO se introduce un cuarto tier en el enum `nivelRiesgo`.
+
+### Parte 8 — Stop Rules
+
+Tres tipos de stop, todos load-bearing:
+
+- **Halt** — restricciones en conflicto, confianza cae 2x consecutivas,
+  `maxTurnos` alcanzado.
+- **Escalate** — fuera de scope, tema legal/compliance detectado,
+  frustración persistente.
+- **Complete** — outcomes alcanzados, usuario confirma.
+
+> "Halt and escalate are the load-bearing branches, and /goal ships
+> neither." (línea 271)
+
+**Dónde vive en SWL**:
+- `maxTurnos:` en frontmatter — tope de iteraciones.
+- Recovery Catalog en `reglas/seguridad-agentes.md § Recovery Catalog` —
+  reprompt → reduce-autonomy → escalate → terminate.
+- `notificador-swl` para escalado a humano vía Telegram/desktop.
+
+## Cómo aplicar el framework a un agente nuevo
+
+1. Cargar este skill antes de escribir el primer carácter del agente.
+2. Importar `agentes/_intent-spec.md` con `fragmentos: [_intent-spec]`.
+3. Declarar los 4 campos opcionales del schema:
+   - `strategy:` (Parte 1)
+   - `healthMetrics:` (Parte 4)
+   - `steering:` (Parte 6 — soft)
+   - `hardGuardrails:` (Parte 6 — hard)
+4. Verificar que `description` cubre Parte 2 (Objective).
+5. Verificar que `nivelRiesgo` mapea a Parte 7 (Autonomy Boundaries).
+6. Verificar que `maxTurnos` está declarado si hay loop interno (Parte 8).
+7. Org Context (Parte 5) vive en CLAUDE.md — no se duplica en el agente.
+8. Desired Outcomes (Parte 3) vive en PLAN.md de cada invocación — no se
+   hardcodea en el agente.
+
+## Anti-patrones específicos a evitar
+
+- **`steering` que debería ser `hardGuardrails`**: "no eliminar tablas"
+  sin hook `proteccion-rutas.js` o equivalente. Si importa, va en
+  arquitectura.
+- **Health metrics como outcomes negados**: "no degradar latencia" es
+  health metric; "latencia < 200ms p95" es outcome. La diferencia: outcome
+  se persigue, health metric se protege mientras se persigue.
+- **Strategy demasiado genérica**: "código limpio y mantenible" no es
+  strategy de un agente — es default. Strategy debe nombrar el tradeoff
+  específico que ese agente prioriza.
+- **Autonomy Boundaries por ego, no por riesgo**: `nivelRiesgo: ALTO` no
+  es prestigio; es declaración de que el agente toca cosas
+  irreversibles. Si BAJO o MEDIO basta, no inflar.
+- **Stop Rules ausentes**: agente sin `maxTurnos` ni recovery declarado
+  puede entrar en loop infinito. Default seguro: 10-15 turnos.
+
+## Gotchas no obvios
+
+- **Health metrics no se enforce por sí solas**: el agente las lee y se
+  comporta más conservador, pero NO hay hook que las verifique
+  automáticamente. Diseñar telemetría que las capture si el agente es
+  crítico.
+- **`steering` y `hardGuardrails` aceptan `@reglas/X.md`**: cuando una
+  restricción es global, no copiar el texto — referenciar la regla
+  evita drift.
+- **El framework no resuelve ambigüedad de objetivos en conflicto**:
+  si dos health metrics chocan entre sí, la prioridad debe declararse
+  como tradeoff en `strategy`.
+
+## Referencia rápida — campos por nivelRiesgo
+
+| Campo | BAJO | MEDIO | ALTO |
+|---|---|---|---|
+| `description` (Parte 2) | Obligatorio | Obligatorio | Obligatorio |
+| `nivelRiesgo` (Parte 7) | Obligatorio | Obligatorio | Obligatorio |
+| `maxTurnos` (Parte 8) | Recomendado | Recomendado | Obligatorio |
+| `strategy` (Parte 1) | Opcional | Opcional | Obligatorio |
+| `healthMetrics` (Parte 4) | Opcional | Opcional | Obligatorio |
+| `steering` (Parte 6) | Opcional | Recomendado | Recomendado |
+| `hardGuardrails` (Parte 6) | Opcional | Recomendado | Obligatorio |
+| `fragmentos: [_intent-spec]` | Opcional | Opcional | Obligatorio |
+
+## Origen
+
+Skill creado el 2026-05-18 como parte de Opción B de integración
+`temp/Lead-agents-like-humans.md` + `temp/DDIA*.md`. Ver ADR-0025 para la
+decisión de scope. Fragment compartido `_intent-spec` es la
+versión system-prompt-embebida; este skill es la versión invocable on-demand.

package/habilidades/reducir-entropia/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: reducir-entropia
+description: >
+  Skill manual-only para minimizar el tamaño total del codebase. Mide el
+  éxito por la cantidad de código final, no por el esfuerzo de escribirlo.
+  Sesgo hacia la eliminación: 50 líneas que borran 200 = win neto; 14
+  funciones para no escribir 2 = pérdida neta. Cargar SOLO cuando el
+  usuario lo pide explícitamente — no se activa por similitud o keyword.
+  Adaptación de `reducing-entropy` de agent-toolkit.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep, Glob, Bash]
+exclusiones:
+  - "No cargar automáticamente — solo cuando el usuario lo pide explícitamente con 'reducir entropía', 'minimizar código', 'qué podemos borrar'. La activación automática contradice el propósito."
+  - "No cargar para greenfield (proyecto nuevo) donde aún no hay código que reducir."
+  - "No cargar contra código en framework con convenciones fuertes (Django, Rails, NestJS) — pelearse con el framework siempre suma código, no resta."
+  - "No cargar para código bajo requerimiento regulatorio que mandata cierta estructura (auditoría, compliance, separación de concerns legal)."
+evolvable: true
+---
+
+# Habilidad: Reducir entropía
+
+Más código engendra más código. La entropía se acumula. Este skill sesga
+hacia el codebase más pequeño posible.
+
+**Pregunta central**: "¿Cómo se ve el codebase **después**?"
+
+## Antes de empezar
+
+Verificar que el usuario invocó este skill explícitamente. No activarlo
+por keyword similar ("refactor", "limpiar"). Si la invocación es ambigua,
+preguntar:
+
+> ¿Quieres que aplique el lente de *reducir-entropia* (sesgo hacia
+> borrar) o un refactor estándar (cambia estructura sin reducir
+> tamaño)?
+
+Si la respuesta es "refactor", NO cargar este skill — usar
+`legacy-code-rescue` o `revisor-codigo-swl`.
+
+## Cuándo cargar
+
+- Usuario pide explícitamente: "reduce entropía", "minimiza este código",
+  "¿qué podemos borrar?", "el codebase está gordo".
+- Tras un sprint donde se duplicaron utilidades sin consolidar.
+- Al cerrar una fase grande para limpiar deuda antes de la siguiente.
+
+## Cuándo NO cargar
+
+Listado en `exclusiones` del frontmatter — incluye activación automática,
+greenfield, frameworks opinionados y requerimientos regulatorios.
+
+---
+
+## La meta
+
+La meta es **menos código total en el codebase final** — no menos código
+por escribir ahora.
+
+- Escribir 50 líneas que borran 200 = win neto.
+- Mantener 14 funciones para no escribir 2 = pérdida neta.
+- "Sin churn" no es la meta. Menos código es la meta.
+
+**Medir el estado final, no el esfuerzo.**
+
+## Tres preguntas
+
+### 1. ¿Cuál es el codebase mínimo que resuelve esto?
+
+No "cuál es el cambio mínimo" — cuál es el **resultado** mínimo.
+
+- ¿Podrían ser 2 funciones en lugar de 14?
+- ¿Podrían ser 0 funciones (borrar la feature completa)?
+- ¿Qué borraríamos si hiciéramos esto?
+
+### 2. ¿El cambio propuesto resulta en menos código total?
+
+Contar líneas antes y después. Si después > antes, rechazar el cambio.
+
+- "Mejor organizado" pero más código = más entropía.
+- "Más flexible" pero más código = más entropía.
+- "Mejor separación" pero más código = más entropía.
+
+### 3. ¿Qué se puede borrar?
+
+Cada cambio es una oportunidad para borrar. Preguntar:
+
+- ¿Qué vuelve obsoleto este cambio?
+- ¿Qué solo existía por lo que estamos reemplazando?
+- ¿Cuál es el máximo que podríamos remover?
+
+---
+
+## Red flags (justificaciones que NO compensan más código)
+
+- **"Keep what exists"** — sesgo de status quo. La pregunta es código
+  total, no churn.
+- **"Esto añade flexibilidad"** — flexibilidad para qué. YAGNI.
+- **"Mejor separación de concerns"** — más archivos/funciones = más
+  código. La separación no es gratis.
+- **"Type safety"** — vale cuántas líneas. A veces runtime checks en
+  menos código gana.
+- **"Más fácil de entender"** — 14 cosas no son más fáciles que 2 cosas.
+- **"Por si acaso lo necesitamos"** — YAGNI. Borrar.
+
+## Cuándo NO aplica (después de cargar el skill)
+
+Aunque el skill se haya cargado, hay casos donde la respuesta correcta
+es "no hay nada que reducir":
+
+- El codebase ya es mínimo para lo que hace.
+- Estás dentro de un framework con convenciones fuertes (no peles contra
+  el framework — más esfuerzo, más bugs, mismo tamaño).
+- Hay requerimientos regulatorios o de compliance que mandan estructura
+  (auditoría, separación legal, accesibilidad WCAG).
+- El código es bibliográficamente pequeño pero **estructuralmente
+  necesario** (DI containers, contracts entre módulos, schemas de
+  validación legal).
+
+Si alguna de estas aplica, decirlo y NO insistir en borrar.
+
+---
+
+## Reglas obligatorias
+
+1. **Manual-only**: este skill no se carga por matcher ni por keyword
+   similar. Solo por invocación explícita. **Por qué**: el sesgo hacia
+   borrar es agresivo; aplicarlo cuando el usuario no lo pidió destruye
+   trabajo legítimo.
+
+2. **Contar líneas antes/después**: cada propuesta de cambio incluye el
+   delta de LOC. **Por qué**: sin números, "reducir" se vuelve subjetivo
+   — y subjetivamente, "está mejor" suele significar "más código pero
+   organizado".
+
+3. **Borrar > extraer**: ante la duda entre "borrar la feature" y
+   "refactorizar la feature", priorizar borrar. **Por qué**: la feature
+   no usada cuesta mantenimiento aunque esté "bien organizada".
+
+4. **Red flags requieren justificación cuantitativa**: si alguien
+   defiende un cambio con "más flexible", exigir números de cuántas
+   variaciones reales se anticipan en los próximos 6 meses. **Por qué**:
+   "flexible" sin métrica = optimización para casos imaginarios.
+
+5. **Si el codebase ya es mínimo, decirlo y parar**: no forzar reducciones
+   inventadas. **Por qué**: borrar de un codebase ya mínimo introduce
+   bugs sin reducir entropía real.
+
+6. **Respetar contratos públicos**: APIs públicas con consumidores no se
+   borran sin plan de migración. **Por qué**: la entropía se reduce
+   internamente, no rompiendo a terceros.
+
+---
+
+## Relación con otras herramientas SWL
+
+- **`legacy-code-rescue`**: refactoriza código heredado preservando
+  comportamiento. Este skill **borra** comportamiento que no se necesita.
+  Opuestos por diseño.
+- **`revisor-codigo-swl`**: detecta code smells y aplica reglas de
+  estilo. Este skill aplica un único lente (tamaño total) — más radical.
+- **Regla `estilo-codigo.md § DRY`**: dice "no duplicar conocimiento".
+  Este skill dice "borrar si no hace falta". DRY puede generar más
+  código (extraer helper); este skill prefiere borrar el caller.
+- **Skill `analisis-previo-tareas-grandes`**: si reducir entropía resulta
+  en cambios masivos (>10 archivos), aplicar tabla comparativa + 3
+  opciones antes de borrar.
+- **Regla `arreglar-al-detectar.md`**: prohíbe deuda silenciosa. Si al
+  reducir se descubren funcionalidades no documentadas, reportar antes
+  de borrar.
+
+---
+
+## Ejemplo de uso
+
+Usuario: *"el módulo `utils/` está gigante, ¿qué podemos borrar?"*.
+
+Agente carga este skill y aplica las tres preguntas:
+
+```
+### Análisis de entropía — utils/ (1,847 LOC)
+
+**Inventario**: 23 archivos, 67 funciones exportadas.
+
+**Pregunta 1 — codebase mínimo**: para los casos de uso reales (verificados
+con `grep -rn 'from utils'` en backend/ y frontend/), 12 funciones cubren
+el 90% de los imports. Las otras 55 funciones tienen 0-2 imports cada una.
+
+**Pregunta 2 — delta neto**: borrar las 55 funciones poco usadas elimina
+1,420 LOC. Inlinar los 2-3 imports de cada una añade ~80 LOC en sus
+callers. Delta: -1,340 LOC.
+
+**Pregunta 3 — qué se puede borrar**:
+- `utils/dateFormatters.js` (8 funciones, 240 LOC) — 6 funciones no
+  usadas; 2 usadas, inlinables en el caller único.
+- `utils/stringHelpers.js` (12 funciones, 380 LOC) — 9 no usadas; 3
+  duplican métodos nativos (`String.prototype.padStart` etc.).
+- `utils/legacyAdapter.js` (320 LOC) — 0 imports activos tras migración
+  de v3 → v4 en 2025-Q4. Candidato a borrado completo.
+
+**Red flags detectadas en el código actual**:
+- "Por si acaso" en 3 helpers que nadie llama.
+- "Type safety" en wrappers que solo agregan annotations sin valor.
+
+**Propuesta**:
+1. Borrar `legacyAdapter.js` (sin imports). -320 LOC.
+2. Borrar las 9 funciones no usadas de `stringHelpers.js`. -270 LOC.
+3. Borrar las 6 funciones no usadas de `dateFormatters.js`. -180 LOC.
+4. Mantener las 12 funciones core (alta concurrencia).
+
+**Delta total proyectado**: -770 LOC (de 1,847 → 1,077, -42%).
+
+**Lo que NO conviene borrar**:
+- `utils/validation/` — schemas de validación legal (compliance).
+- `utils/auth/` — contratos con frontend; cambio rompería runtime.
+
+¿Procedo con el plan en 3 commits atómicos?
+```
+
+El usuario decide. El agente NO borra antes de aprobación explícita.