@saulwade/swl-ses 1.0.0

package/habilidades/guardrail-semantico/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: guardrail-semantico
+description: >
+  Patrón de validación pre/post ejecución de agentes con "tripwire" para decidir
+  si permitir, degradar modelo o bloquear. Cargar cuando se diseñen hooks PreToolUse
+  de validación semántica, cuando se implemente control de costos por nivel de
+  complejidad, o cuando se quiera observar si un subagente podría ejecutarse con
+  un modelo menos costoso. Basado en el patrón InputGuardrail/OutputGuardrail de
+  openai-agents-python.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write]
+exclusiones:
+  - "No cargar para guardrails de seguridad (detectar operaciones destructivas, escritura en rutas prohibidas, secretos en output) — eso es `reglas/seguridad-agentes.md` y el hook `risk-scoring`; este skill evalúa complejidad semántica para degradación de modelo, no riesgo operacional."
+  - "No cargar si el guardrail objetivo va directamente a modo `blocking` sin datos de observación — el propio skill requiere ≥50 activaciones en modo `observational` antes de considerar `blocking`; cargar el skill para diseñar el guardrail, no para saltarse ese requisito."
+  - "No cargar para configurar permisos de tools o allowedTools de un agente — eso es `estructura-proyecto-claude` y `seguridad-agentes`; este skill diseña la lógica de tripwire para degradación de modelo."
+  - "No cargar para guardrails sobre agentes con `nivelRiesgo: ALTO` — el Criterio 3 es determinista: esos agentes nunca se degradan; diseñar guardrails para ellos no tiene efecto."
+tags: [patron-diseño, costos, modelos, guardrails, agentes]
+provenance:
+  origin: imported
+  created_at: "2026-04-19"
+  confidence: 0.75
+  author: saul.wade@gmail.com
+---
+# Guardrail Semántico — Validación con tripwire para agentes
+
+## Propósito
+
+Un guardrail semántico es una capa de validación que se ejecuta **antes o después**
+de la tarea de un agente para decidir si proceder, degradar el modelo, o bloquear.
+El "tripwire" es la condición booleana que activa la respuesta del guardrail.
+
+A diferencia de los guardrails de seguridad (que bloquean operaciones peligrosas),
+el guardrail semántico evalúa la **complejidad semántica** del input para decidir
+si se justifica el costo del modelo seleccionado.
+
+## Cuándo cargar este skill
+
+- Al diseñar hooks `PreToolUse` que evalúan prompts antes de invocar un subagente.
+- Al implementar degradación de modelo basada en complejidad de tarea.
+- Al revisar si `guardrail-modelo.js` necesita nuevos criterios de tripwire.
+- Al analizar logs de `.planning/evolucion/guardrail-observaciones.jsonl`.
+
+---
+
+## Componentes del patrón
+
+### GuardrailFunctionOutput
+
+Estructura de retorno de toda función de guardrail:
+
+```js
+// GuardrailFunctionOutput — contrato de retorno
+{
+  tripwire_triggered: boolean,  // true = aplicar acción (degradar/bloquear)
+  output_info: any,             // datos de análisis para diagnóstico
+  metadata: {
+    razon: string,              // descripción legible del criterio activado
+    confidence: number,         // 0.0-1.0 de certeza del tripwire
+    modelo_sugerido: string,    // 'haiku' | 'sonnet' | 'opus' | null
+  }
+}
+```
+
+### InputGuardrail (pre-ejecución)
+
+Se ejecuta **antes** de que el agente reciba su tarea. Analiza el prompt del
+subagente para decidir si la complejidad justifica el modelo seleccionado.
+
+```js
+// Pseudocódigo del patrón InputGuardrail
+function inputGuardrail(promptTexto, agenteConfig) {
+  const analisis = analizarComplejidad(promptTexto);
+  const nivelRiesgo = agenteConfig.nivelRiesgo || 'MEDIO';
+
+  // override: agentes de alto riesgo nunca se degradan
+  if (nivelRiesgo === 'ALTO') {
+    return { tripwire_triggered: false, output_info: analisis, metadata: { razon: 'override-alto-riesgo' } };
+  }
+
+  const tripwire = analisis.esTrivial || analisis.tienePalabrasLigeras;
+  return {
+    tripwire_triggered: tripwire,
+    output_info: analisis,
+    metadata: {
+      razon: analisis.razon,
+      confidence: analisis.confidence,
+      modelo_sugerido: tripwire ? 'haiku' : null,
+    }
+  };
+}
+```
+
+### OutputGuardrail (post-ejecución)
+
+Se ejecuta **después** de que el agente entregó su resultado. Evalúa la calidad
+del output para retroalimentar el sistema de confianza.
+
+```js
+// Pseudocódigo del patrón OutputGuardrail
+function outputGuardrail(resultado, agenteConfig) {
+  const problemas = detectarProblemas(resultado);
+  return {
+    tripwire_triggered: problemas.length > 0,
+    output_info: { problemas },
+    metadata: { razon: problemas.join('; '), confidence: 0.8 }
+  };
+}
+```
+
+### Modos de ejecución
+
+| Modo | Comportamiento | Cuándo usar |
+|------|---------------|-------------|
+| `blocking` | Síncrono. Si tripwire activa, aborta la tarea. | Validaciones de seguridad críticas |
+| `run_in_parallel` | No bloquea. Registra el tripwire sin interrumpir. | Observación de patrones, primera versión de guardrails nuevos |
+| `observational` | Solo registra. Nunca actúa. | Acumulación de datos pre-activación |
+
+**Regla de introducción**: todo guardrail nuevo DEBE iniciar en modo `observational`
+o `run_in_parallel` durante al menos 50 activaciones antes de activar el modo
+`blocking`. Esto previene falsos positivos en producción sin datos.
+
+---
+
+## Criterios propuestos de tripwire para degradación de modelo
+
+### Criterio 1 — Tarea trivial por longitud
+
+**Señal**: prompt < 200 caracteres Y sin palabras clave de decisión crítica.
+**Acción**: sugerir degradación Opus → Sonnet, Sonnet → Haiku.
+**Confianza**: 0.6 (longitud no garantiza trivialidad).
+
+```js
+const esTrivialPorLongitud = (texto) =>
+  texto.length < 200 &&
+  !/arquitectura|seguridad|diseño|decisión|riesgo|critico|irreversible/i.test(texto);
+```
+
+### Criterio 2 — Palabras clave de tarea ligera
+
+**Señal**: el prompt contiene verbos de operación determinista.
+**Acción**: forzar degradación a Haiku si el agente no es ALTO riesgo.
+**Confianza**: 0.75.
+
+```js
+const PALABRAS_TAREA_LIGERA = /\b(lista|formatea|muestra|busca|cuenta|consulta|renombra|copia|mueve)\b/i;
+const esTareaLigera = (texto) => PALABRAS_TAREA_LIGERA.test(texto);
+```
+
+### Criterio 3 — Override por nivelRiesgo ALTO
+
+**Señal**: el frontmatter del agente invocado declara `nivelRiesgo: ALTO`.
+**Acción**: NUNCA degradar. Ignorar criterios 1 y 2.
+**Confianza**: 1.0 (regla determinista).
+
+Este criterio protege a: `orquestador-swl`, `arquitecto-swl`, `revisor-seguridad-swl`,
+`producto-prd-swl` y cualquier agente con decisiones irreversibles de arquitectura.
+
+### Criterio 4 — Agente ya en modelo mínimo
+
+**Señal**: el agente invocado ya usa `model: haiku` o `model: claude-haiku-*`.
+**Acción**: no aplicar guardrail (no hay degradación posible).
+**Confianza**: 1.0.
+
+---
+
+## Casos donde NO aplicar
+
+- Agentes con `model: claude-opus-4-7` explícito en frontmatter y `nivelRiesgo: ALTO`.
+- Input que ya pasó por otro guardrail en la misma cadena de delegación.
+- Sesiones de research abierto (`/swl:discutir-fase`, `/swl:brainstorm`) donde
+  la amplitud del análisis es el objetivo.
+- Tareas con keywords mixtas donde criterio 1 y criterio 2 se contradicen:
+  en caso de conflicto, NO degradar (conservador).
+
+---
+
+## Anti-patrones
+
+### Degradación silenciosa
+
+El guardrail que baja el modelo sin notificar al usuario es una violación del
+principio de "no fallback silencioso" (`reglas/seguridad-agentes.md`). Siempre
+emitir un nudge visible antes o durante la degradación.
+
+```
+MAL:  modificar silenciosamente el modelo en el payload sin registrar
+BIEN: emitir nudge + registrar en guardrail-observaciones.jsonl + retornar exit 0
+```
+
+### Tripwire que degrada agentes `model: inherit`
+
+Los agentes con `model: inherit` reciben el modelo del padre. Degradarlos en el
+guardrail rompería la cadena de herencia intencional del orquestador. El hook
+`guardrail-modelo.js` DEBE verificar esto antes de aplicar cualquier criterio.
+
+### Activar blocking sin datos de observación
+
+Pasar de modo `observational` a `blocking` sin revisar las observaciones acumuladas
+es una fuente garantizada de falsos positivos. El ciclo correcto:
+
+1. Deploy en modo `observational` (exit 0 siempre).
+2. Revisar `.planning/evolucion/guardrail-observaciones.jsonl` tras ≥50 activaciones.
+3. Calcular tasa de falsos positivos. Si < 5%, considerar `run_in_parallel`.
+4. Solo con tasa < 2% y aprobación manual, activar `blocking`.
+
+### Lógica de negocio en el guardrail
+
+El guardrail evalúa complejidad semántica, no lógica de negocio. No debe:
+- Validar permisos del usuario.
+- Verificar que el agente existe en el sistema.
+- Modificar el payload del agente invocado (solo observar y reportar).
+
+---
+
+## Ejemplo de uso concreto
+
+Escenario: el orquestador invoca al `notificador-swl` con un prompt corto.
+El hook `guardrail-modelo.js` intercepta la invocación PreToolUse:
+
+```js
+// Fragmento del hook guardrail-modelo.js
+const prompt = payload?.tool_input?.prompt || '';
+const agenteNombre = payload?.tool_input?.agent || '';
+
+const tripwire = esTrivialPorLongitud(prompt) || esTareaLigera(prompt);
+
+if (tripwire) {
+  // Registrar observación
+  const evento = {
+    timestamp: new Date().toISOString(),
+    agente: agenteNombre,
+    modelo_actual: 'sonnet',
+    modelo_sugerido: 'haiku',
+    razon_tripwire: 'prompt-corto-sin-keywords-criticas',
+    prompt_length: prompt.length,
+  };
+  fs.appendFileSync(GUARDRAIL_LOG, JSON.stringify(evento) + '\n');
+
+  // Nudge al usuario — visible, no bloquea
+  process.stderr.write(
+    `[guardrail-modelo] El agente '${agenteNombre}' podría ejecutarse con 'haiku' ` +
+    `(menos costoso). Razón: prompt corto sin keywords críticas (${prompt.length} chars). ` +
+    `Ver .planning/evolucion/guardrail-observaciones.jsonl\n`
+  );
+}
+// exit 0 siempre — modo observacional
+process.exit(0);
+```
+
+**Evento JSONL resultante** en `.planning/evolucion/guardrail-observaciones.jsonl`:
+
+```jsonl
+{"timestamp":"2026-04-19T14:23:01.000Z","agente":"notificador-swl","modelo_actual":"sonnet","modelo_sugerido":"haiku","razon_tripwire":"prompt-corto-sin-keywords-criticas","prompt_length":87}
+```
+
+---
+
+## Checklist para implementar un guardrail nuevo
+
+- [ ] El guardrail tiene un nombre descriptivo y un criterio explícito de tripwire.
+- [ ] Inicia en modo `observational` (exit 0 siempre).
+- [ ] El override `nivelRiesgo: ALTO` está implementado.
+- [ ] El caso `model: inherit` está excluido.
+- [ ] El caso "agente ya en modelo mínimo" está excluido.
+- [ ] Se registra en JSONL append-only (no sobreescribir).
+- [ ] Emite nudge legible con prefijo `[guardrail-*]`.
+- [ ] Está protegido con opt-in de variable de entorno.
+- [ ] El criterio de promoción a `run_in_parallel`/`blocking` está documentado.
+
+## Cuándo NO cargar
+
+- Se diseñan guardrails para detectar operaciones destructivas, escritura en rutas prohibidas o secretos en output — eso es `reglas/seguridad-agentes.md` y `risk-scoring`; este skill evalúa complejidad semántica para degradación de costo de modelo, no riesgo operacional.
+- El agente objetivo tiene `nivelRiesgo: ALTO` en frontmatter — el Criterio 3 es determinista: los agentes de alto riesgo nunca se degradan, por lo que diseñar un guardrail para ellos no tiene efecto.
+- Se necesita configurar `allowedTools` o permisos de tools — eso es `estructura-proyecto-claude` y `seguridad-agentes`; este skill diseña la lógica de tripwire semántico.
+- Se quiere activar un guardrail en modo `blocking` sin haber acumulado datos de observación — el skill requiere ≥50 activaciones en modo `observational` como precondición; usar este skill para diseñar el guardrail respetando ese ciclo, no para saltárselo.
+
+## Gotchas / Errores comunes no obvios
+
+- **Tripwire por longitud (< 200 chars) degrada un prompt corto pero arquitectónicamente crítico**: un prompt de 150 caracteres como "Diseñar la estructura de datos para el módulo de facturación" activa el Criterio 1 y sugiere degradar a Haiku. Causa: la longitud es una señal débil de trivialidad (confianza 0.6 según el skill). Solución: combinar siempre Criterio 1 con la ausencia de keywords críticas — el regex de palabras clave debe incluir "diseñar", "estructura", "arquitectura", "módulo" además de las ya listadas; prompts cortos con decisiones de diseño deben resistir la degradación.
+- **`model: inherit` no verificado antes de aplicar degradación**: el guardrail baja el modelo de un sub-agente que hereda del orquestador, rompiendo la cadena de herencia intencional. Causa: el hook no verifica el campo `model` del frontmatter del agente invocado antes de aplicar los criterios. Solución: el primer check del guardrail debe ser `if (agenteConfig.model === 'inherit') return { tripwire_triggered: false }` — la herencia de modelo es una decisión del orquestador que el guardrail no debe anular.
+- **JSONL de observaciones escrito con `atomicWriteJSON` en lugar de `appendFileSync`**: el archivo `guardrail-observaciones.jsonl` pierde eventos anteriores porque se sobreescribe en cada activación. Causa: confundir archivos de estado (usan `atomicWriteJSON`) con archivos de eventos de alta frecuencia (usan `appendFileSync`). Solución: `guardrail-observaciones.jsonl` es un log de eventos — siempre `fs.appendFileSync(GUARDRAIL_LOG, JSON.stringify(evento) + '\n')`; el ejemplo de código en el skill ya lo muestra correctamente.
+- **Criterios 1 y 2 en conflicto sin conservar el modelo**: un prompt de 150 chars (Criterio 1 → degradar) contiene la palabra "lista" (Criterio 2 → degradar) pero también "arquitectura" (keyword crítica → no degradar). El guardrail actúa sobre los primeros dos criterios e ignora el tercero. Causa: no implementar la regla de resolución de conflictos del skill ("en caso de conflicto, NO degradar"). Solución: el flujo de decisión debe verificar todos los criterios antes de emitir el tripwire — si algún criterio sugiere no degradar (keyword crítica presente), el resultado es `tripwire_triggered: false` independientemente de los demás.

package/habilidades/harness-claude-code/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: harness-claude-code
+description: >
+  Disciplina operacional del harness de Claude Code para reducir consumo de
+  tokens y proteger el cache de prompt. Cubre las 4 causas raíz de quemar
+  cuota antes de tiempo (cache misses, context bloat, modelo/effort
+  incorrecto, formato de input ineficiente), 5 session moves (compact,
+  clear, rewind, sub-agentes, skills as agents), variables de entorno
+  recomendadas, tag files con @, /effort per-prompt y route-out a OpenRouter.
+  Cargar cuando el usuario reporte "se acabó la cuota", se prepare una
+  sesión Opus larga (>2h), se planifique adopción de MCP servers, o se
+  detecte context-rot recurrente.
+version: "1.0.0"
+evolved: false
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para teoría general de context-rot y compactación — usar `compactacion-contexto`. Este skill cubre operación day-to-day del harness Claude Code; aquel cubre principios de gestión de contexto independientes de la herramienta."
+  - "No cargar para diseño/escritura de skills SWL — usar `meta-skills-estandar` y `reglas/skills-estandar.md`. Este skill cubre uso eficiente de skills, no su construcción."
+  - "No cargar para resolución de errores específicos del runtime (CLI no arranca, MCP no conecta) — esos son problemas técnicos del CLI, no del harness operacional."
+  - "No cargar para análisis de costo histórico o dashboards — usar `swl-dashboard` o `/swl:metricas`. Este skill cubre PREVENCIÓN del gasto excesivo, no el reporte post-hoc."
+evolvable: true
+---
+
+# Harness Claude Code — disciplina operacional
+
+Origen: artículo "Claude Code's Limits Are Generous. The Problem Is Your
+Harness." más experiencia operativa SWL.
+
+Tesis: los límites de Claude Code Max son generosos. Si te quedaste sin
+cuota antes de tiempo, no es Anthropic — es tu harness (configuración +
+sesión + tools + modelo + formato de input). Cuatro causas raíz, todas
+del lado del usuario.
+
+## Cuándo cargar
+
+- El usuario reporta "se acabó la cuota antes de tiempo".
+- Se diagnostica una sesión con context-rot recurrente o alertas críticas
+  falsas/persistentes.
+- Se prepara una sesión Opus larga (>2h) o adopción de MCP servers nuevos.
+- Se va a ejecutar un workflow agéntico complejo y se quiere protección
+  proactiva del cache.
+
+## Cuándo NO cargar
+
+- La tarea es entender principios generales de compactación de contexto
+  independientes del tool — usar `compactacion-contexto`.
+- Se va a escribir un skill SWL nuevo — usar `meta-skills-estandar`.
+- El problema es un error del runtime (CLI no inicia, MCP no responde) —
+  ese es problema técnico, no operacional.
+- Se quiere ver costo histórico — usar `swl-dashboard` o `/swl:metricas`.
+
+---
+
+## Las 4 causas raíz
+
+### 1. Cache misses
+
+El prompt cache es la palanca económica más grande:
+
+| Operación | Costo |
+|-----------|-------|
+| Cache read | 0.1× (90% descuento) |
+| Cache write 5min | 1.25× |
+| Cache write 1h | 2× (solo API) |
+| Cache refresh on hit | gratis |
+
+Cada hit resetea el TTL sin costo. El prefijo se mantiene caliente mientras
+no cambie. **Hit rate sano: ~90% en 5-min default.**
+
+**Reglas operacionales** (ver también `reglas/harness-claude-code.md`):
+
+- NO agregar/quitar MCP servers mid-session
+- NO usar `/model` mid-session
+- NO modificar tools permitidos mid-session
+- Si necesitas cambio: `/clear` y reinicia
+
+Si el hit rate cae bajo 80%, algo en el harness está invalidando el prefijo
+entre turnos. Investigar antes de seguir trabajando.
+
+### 2. Context bloat
+
+Para Opus 4.7 el default es 1M context. Es caro y rara vez necesario.
+
+**Variables de entorno recomendadas** para sesiones largas:
+
+```jsonc
+// .claude/settings.json
+{
+  "env": {
+    "CLAUDE_CODE_DISABLE_1M_CONTEXT": "1",      // 200K en lugar de 1M
+    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "80"     // auto-compact al 80%
+  }
+}
+```
+
+NO son universales — solo si el codebase no requiere 1M y se ve context
+bloat real. Para sesiones que sí necesitan 1M (análisis de codebase
+masivo), dejar el default.
+
+### 3. Modelo y effort incorrectos
+
+**3 dials separados**: modelo de sesión, modelo de delegación, effort por prompt.
+
+**Modelo de sesión** (lock al inicio):
+- Sonnet session: barato; sin acceso a Opus en padre. Bueno si todo cabe en Sonnet.
+- Opus session + delegate: padre con Opus para planning/tradeoffs; sub-agentes
+  Sonnet/Haiku para tactical work. Default para trabajo mixto.
+
+**`/effort` per-prompt** (no per-session):
+
+| Level | Cuándo |
+|-------|--------|
+| `/effort low` | fixes rápidos, tareas mecánicas |
+| `/effort medium` | la mayoría de prompts (gran ahorro vs default) |
+| `/effort high` | razonamiento exigente |
+| `/effort xhigh` | default para coding agéntico Opus 4.7 |
+| `/effort max` | diminishing returns; raramente vale 2× costo extra |
+
+### 4. Formato de input ineficiente
+
+| Input | Costo bruto | Solución |
+|-------|-------------|----------|
+| PDF directo via Read tool | Carga como imagen, ~10× tokens | `pdftotext` o `markitdown` ANTES |
+| Página web dinámica | Playwright + screenshots | `agent-browser` (~82% menos tokens) |
+| Codebase grande (>500 archivos) | Re-lectura completa cada review | `code-review-graph` pip (6.8-49× menos tokens) |
+| Vague prompt | Múltiples turnos para clarificar | Spec prompt: rutas, componentes, I/O, restricciones |
+
+---
+
+## Las 5 session moves
+
+### Move 1 — `/compact` proactivo al 50% o tras cada tarea grande
+
+NO esperes al auto-compact. El auto dispara tarde, empuja el contexto
+sobre el threshold y obliga a recargar prefijo.
+
+### Move 2 — `/clear` entre tareas no relacionadas
+
+Sesión nueva = prefijo fresco. Si pasas de frontend a backend, abre nueva.
+
+### Move 3 — `/rewind` cuando un turno salió mal
+
+Más barato que pelear con contexto contaminado. Especialmente útil tras
+una respuesta del modelo que tomó dirección incorrecta.
+
+### Move 4 — Sub-agentes para trabajo paralelizable o bulk
+
+Bloque a copiar en CLAUDE.md del proyecto:
+
+```markdown
+## Task Delegation
+
+Spawn sub-agentes para aislar contexto, paralelizar trabajo
+independiente o procesar tareas bulk-mecánicas. NO spawnear cuando el
+padre necesita el razonamiento, cuando la síntesis requiere mantener
+todo junto, o cuando el spawn overhead domina.
+
+Modelo más barato que pueda hacer la subtarea bien:
+- Haiku: bulk mecánico, sin juicio
+- Sonnet: research scoped, exploración de código, síntesis in-scope
+- Opus: subtareas con planning real o tradeoffs
+
+Si un sub-agente detecta que necesita un tier más alto que el suyo,
+regresa al padre. El padre es dueño del output final y la síntesis
+cross-spawn.
+```
+
+### Move 5 — Skills as agents (`agent: true` + `model:`)
+
+Patrón Anthropic nativo: agregar `agent: true` y `model:` al frontmatter
+de un SKILL.md y el skill se ejecuta en su propio sub-agente con su
+propio modelo.
+
+Ejemplo: skill `tldr-pdf` con `agent: true, model: sonnet`. El padre le
+pasa una ruta de PDF; el skill extrae con `pdftotext`, lee el output,
+devuelve 200 palabras al padre. El PDF completo nunca toca el contexto
+del padre.
+
+Útil para: procesamiento de archivos grandes, búsqueda en codebase,
+extracción de bullets de docs largos. Ver detalles en
+`Skill("meta-skills-estandar")` sección "Skills as agents".
+
+---
+
+## Tag files con `@`
+
+En lugar de pedirle a Claude que busque, dale la ruta directamente:
+`@ docs/diseno.md ¿qué cambios hace falta para X?` evita tool calls de
+Glob/Grep — es 1 sola lectura.
+
+---
+
+## Route in vs route out
+
+### Route in — modelo del padre en CLAUDE.md
+
+Documenta delegación explícita en CLAUDE.md del proyecto. Opus 4.7
+delega menos por defecto que 4.6, hay que pedirlo de forma explícita
+(ver bloque de Task Delegation arriba).
+
+### Route out — usar otro provider
+
+Si llegas al límite de Pro/Max/Team pero quieres mantener la interfaz de
+Claude Code:
+
+```jsonc
+// .claude/settings.json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://openrouter.ai/api",
+    "ANTHROPIC_AUTH_TOKEN": "{API-KEY}",
+    "ANTHROPIC_API_KEY": ""
+  },
+  "model": "z-ai/glm-5.1"
+}
+```
+
+GLM-5.1 ≈ Opus a ~1/12× del costo. Trade-off: cambias de modelo, sí o
+sí pierdes el cache cuando vuelves a Anthropic.
+
+---
+
+## Watch the number — cómo medir
+
+| Necesidad | Herramienta |
+|-----------|-------------|
+| Histórico Pro/Max/Team | `/swl:dashboard` (basado en `phuryn/claude-usage`) |
+| Tokens/costo de la sesión actual | `/swl:metricas` |
+| Porcentaje de contexto usado en vivo | `hooks/linea-estado.js` (status bar) |
+| Alertas cuando contexto se llena | `hooks/monitor-contexto.js` (WARNING ≥65%, CRITICAL ≥75%) |
+| Hit rate de cache (API users) | `platform.claude.com/usage/cache` |
+
+Sin observar la métrica, no puedes optimizarla.
+
+---
+
+## Carga lean — qué desactivar
+
+- MCP servers que no se usan en el proyecto actual.
+- Skills oficiales de Anthropic que no aplican al stack.
+- Tools permitidos: solo los necesarios. Cada tool extra alarga el
+  system prompt y reduce el ratio cache hit.
+- Reglas largas en CLAUDE.md → mover a skills (progressive disclosure
+  SWL ya lo hace por defecto).
+
+---
+
+## Anti-patrones
+
+- **Invocar Claude Code y luego decidir el modelo**: invalida cache.
+- **MCP server "temporal" agregado durante la sesión**: el costo de
+  invalidar el prefijo supera lo que el server aporta.
+- **`/effort max` por reflejo**: 2× costo sin mejora observable salvo
+  en tareas de razonamiento profundo.
+- **PDFs vía Read sin pre-procesar**: ~10× tokens vs `markitdown`.
+- **Pedir a Claude que busque archivos que ya conoces**: gasta tool
+  calls innecesarios. Usa `@ ruta.md`.
+- **No usar `/compact`** y esperar al auto-compact: dispara tarde y caro.
+- **Cambiar de modelo a media sesión**: invalida cache + pierde
+  contexto coherente.
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **`CLAUDE_CODE_DISABLE_1M_CONTEXT=1` aplicado por default a todos los proyectos**: causa truncado de contexto en sesiones que sí requieren 1M (análisis masivo de codebase, refactor cross-module). Causa: tomar la recomendación del artículo como universal. Solución: aplicar SOLO en proyectos donde se observe context bloat real. Para análisis profundos, dejar el default 1M.
+- **Sub-agentes Sonnet/Haiku que delegan al padre Opus pidiendo "más razonamiento"**: el padre acaba haciendo el trabajo que se quería offloadear. Causa: spec del sub-agente vaga. Solución: el padre debe hacer una spec clara con criterios de aceptación; sub-agentes solo escalan si encuentran tradeoff arquitectónico explícito, no por dificultad genérica.
+- **`/clear` mid-session destruye el plan en curso**: usuario pierde el roadmap acumulado. Causa: confundir `/clear` con `/compact`. Solución: `/compact` resume manteniendo conocimiento; `/clear` empieza desde cero. Antes de `/clear`, escribir un handoff a `.planning/COMPACTACION.md` con `/swl:compactar`.
+- **Tag files con `@` apuntando a archivos enormes**: Claude carga el archivo completo en contexto aunque solo necesite una sección. Causa: usar `@` con archivos >500 líneas. Solución: para archivos grandes, citar sección específica en el prompt (`@ src/auth.py líneas 100-150`) o pre-extraer con `Read offset/limit`.
+- **`/effort high` que se queda activo en prompts simples**: el siguiente prompt trivial gasta 2× tokens innecesarios. Causa: el effort se interpreta como "session-wide" cuando es per-prompt. Solución: explícito `/effort medium` (o lo que aplique) en el siguiente prompt si la complejidad bajó.
+
+---
+
+## Integración con SWL
+
+Componentes SWL que cubren necesidades de harness: `/swl:compactar`,
+`/swl:checkpoint`, `/swl:dashboard`, `/swl:metricas`, `/swl:modelo`,
+`/swl:contexto`, hooks `linea-estado.js` + `monitor-contexto.js`,
+`/swl:revisar-impacto` (meta-grafo del sistema SWL) y `code-review-graph`
+pip (opt-in para codebase del usuario, ver `MANUAL_USO.md`).
+
+Cargar este skill cuando esos componentes no son suficientes y hace falta
+el modelo mental completo del harness.
+
+---
+
+## Checklist antes de iniciar sesión Opus larga
+
+- [ ] `.claude/settings.json` con todos los MCP necesarios YA configurados
+- [ ] Modelo elegido y bloqueado (no se cambiará durante la sesión)
+- [ ] Tools permitidos definidos antes de iniciar
+- [ ] `CLAUDE_CODE_DISABLE_1M_CONTEXT` y `CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`
+      configurados si la sesión es larga sin necesidad de 1M
+- [ ] Plan de delegación claro (qué se manda a sub-agente, qué se mantiene
+      en el padre)
+- [ ] PDFs/Office docs pre-procesados con `markitdown`
+- [ ] Para repos grandes: `code-review-graph` instalado y `build` ejecutado
+- [ ] CLAUDE.md del proyecto con bloque de Task Delegation
+- [ ] Saber dónde ver métricas durante la sesión (`/swl:metricas`)