@saulwade/swl-ses 2.5.2 → 2.6.0

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

@@ -1,308 +1,314 @@
----
-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.4"
-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:status 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:status 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** (detalle completo en
-[disciplina-harness-regla](recursos/disciplina-harness-regla.md) — ex-regla
-`reglas/harness-claude-code.md`, absorbida aquí porque su propio texto decía
-"no es de carga obligatoria global" y este skill es su canal bajo demanda):
-
-- 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.8 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.8 |
-| `/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.8
-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:status dashboard` (basado en `phuryn/claude-usage`) |
-| Tokens/costo de la sesión actual | `/swl:status metricas` |
-| Porcentaje de contexto usado en vivo | statusline nativo del CLI (`ctx: N%`) |
-| Guardar estado antes de compactar | `hooks/preservar-estado-pre-compact.js` (PreCompact, dispara en toda compactación manual o automática) |
-| 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
-
-- **Matriz de canales de hooks — stderr con exit 0 es un canal INVISIBLE** [origen: check-update 2026-07-08, el aviso de nuevas versiones se emitió al vacío desde su creación]: en Claude Code, el canal correcto depende del exit code. **exit 0 (éxito)**: solo el stdout llega — como contexto del turno en UserPromptSubmit/SessionStart (o `hookSpecificOutput.additionalContext`); el stderr no lo lee nadie. **exit 2 (bloqueo)**: solo el stderr llega al modelo con la razón del bloqueo; stdout con exit 2 = bloqueo ciego (regla ya conocida, L1 #4 de APRENDIZAJES). Anti-patrón resultante: "hook que funciona perfecto y nadie ve" — todo aviso al usuario desde un hook exitoso DEBE ir a stdout, idealmente con instrucción explícita ("INFORMA AL USUARIO...") para que el modelo lo retransmita. Verificación: correr el hook a mano con un flag de forzado y confirmar en qué canal aparece el mensaje.
-
-- **El payload de los hooks PostToolUse NO trae `model` ni `usage` — pero `transcript_path` SÍ viene y contiene ambos**: un hook que necesite el contexto real o el modelo activo no debe estimarlos por heurística (un contador de invocaciones × tokens promedio divergió >2x del contexto real y nunca se corregía tras `/compact` — caso swl-ses 2026-07-03). Fuente exacta: leer la cola del JSONL de `transcript_path`, tomar el último mensaje `type: 'assistant'` del hilo principal (filtrar `isSidechain: true` — los subagentes tienen OTRO context window) y sumar `usage.input_tokens + cache_read_input_tokens + cache_creation_input_tokens` = tamaño exacto del contexto de esa llamada; `message.model` da el modelo real. Tras `/compact` la siguiente entrada refleja el contexto compactado — la medición se auto-corrige sin resets.
-- **`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ó.
-- **`child_process.spawn(cmd, args, { env: {} })` REEMPLAZA el env del padre con vacío, NO hereda** [CONFIRMADO 2026-05-18]: el cliente MCP de Claude Code (y el de Cursor) lee `mcpServers.X.env` del config JSON y lo pasa literal al spawn. Si la config tiene `"env": {}` explícito, el binario hijo arranca SIN ninguna variable de entorno del padre — rompe la herencia de apiKeys que viven en HKCU/registry. Síntoma: MCP server da `40101 Authorization required` aunque `setx OBSIDIAN_API_KEY` esté correcto en HKCU y curl con esa key responda HTTP 200 al plugin. Causa: Node `child_process.spawn` con `env: {}` ≠ sin `env` option. Solución: **OMITIR la clave `env` por completo en el JSON** (no dejarla vacía). Verificado empíricamente con `spawn(binario, [], { /* sin env */ })` → binario heredó `OBSIDIAN_API_KEY`; `spawn(binario, [], { env: {} })` → binario sin env. El patch SWL para Python (`scripts/lib/mcp_config.py::build_stdio_env`) merge `os.environ + overrides` para corregir el mismo síntoma en el lado Python.
-- **MCP server devuelve auth error con apiKey correcta en disco → el proceso vivo arrancó con apiKey vieja** [CONFIRMADO 2026-05-18]: aunque `~/.cursor/mcp.json` y `~/.claude/settings.json` tengan la apiKey actual del plugin, los procesos del binario MCP (ej. `mcp-obsidian.exe`) que ya están corriendo retuvieron la apiKey del momento de su spawn. Síntoma: actualizar JSONs no soluciona 40101. Solución: `taskkill /F /IM mcp-obsidian.exe /T` (Windows) o `pkill mcp-obsidian` (Unix) + **quit total del cliente parent** (Cursor.exe / claude.exe) — no basta reload de ventana. Al reabrir, el cliente respawnea el binario con env actual. Verificar con `ps -W | grep mcp-obsidian` que solo haya procesos con timestamp posterior al reinicio.
-- **Cursor y Claude Code CLI dentro de Cursor son clientes MCP DISTINTOS con procesos independientes** [CONFIRMADO 2026-05-18]: cuando se ejecuta Claude Code CLI en una terminal embebida de Cursor, hay DOS procesos del binario MCP corriendo simultáneamente — uno por cliente. Cada uno lee SU PROPIA config: Cursor lee `~/.cursor/mcp.json`, Claude Code CLI lee `~/.claude/settings.json` + `<proyecto>/.claude/settings.local.json`. Una apiKey actualizada en uno no propaga al otro. Síntoma observado: el agente AI de Cursor responde MCP OK pero Claude Code CLI da 40101 (o viceversa). Solución: usar variable de entorno persistente del SO (`setx OBSIDIAN_API_KEY` → HKCU\Environment) como single source of truth y dejar configs JSON sin clave `env` para heredar del padre. Cada regeneración de apiKey requiere un solo `setx` + reiniciar Cursor (que reinicia ambos clientes).
-
----
-
-## Integración con SWL
-
-Componentes SWL que cubren necesidades de harness: `/swl:compactar`,
-`/swl:checkpoint`, `/swl:status dashboard`, `/swl:status metricas`, `/swl:modelo`,
-`/swl:contexto`, hook `preservar-estado-pre-compact.js` (PreCompact),
-`/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:status metricas`)
+---
+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.6"
+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:status 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:status 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** (detalle completo en
+[disciplina-harness-regla](recursos/disciplina-harness-regla.md) — ex-regla
+`reglas/harness-claude-code.md`, absorbida aquí porque su propio texto decía
+"no es de carga obligatoria global" y este skill es su canal bajo demanda):
+
+- 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.8 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.8 |
+| `/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.8
+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:status dashboard` (basado en `phuryn/claude-usage`) |
+| Tokens/costo de la sesión actual | `/swl:status metricas` |
+| Porcentaje de contexto usado en vivo | statusline nativo del CLI (`ctx: N%`) |
+| Guardar estado antes de compactar | `hooks/preservar-estado-pre-compact.js` (PreCompact, dispara en toda compactación manual o automática) |
+| 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
+
+- **La frontera de escritura/seguridad de un hook es la raíz del repo git, no el CWD de la sesión** [doble caso real 2026-07-10]: (1) `proteccion-rutas` bloqueó la escritura de `.planning/audit/` en SIGM porque la sesión corría en `sigm/backend/` — el destino estaba dentro del proyecto pero un nivel arriba del CWD; (2) en sistema-verificacion-oic, los hooks de telemetría anclados a `process.cwd()` crearon TRES árboles `.planning/` (raíz + backend + frontend) fragmentando la memoria del proyecto. Causa común: tratar el CWD de arranque como frontera del proyecto — en monorepos la sesión se abre en subdirectorios rutinariamente. Fix de clase: ascender hasta `.git` (directorio o archivo — worktrees) y usar esa raíz como frontera de permisos y como ancla de escritura; si la detección falla → conservador (bloquear / caer al CWD). Aplicado a `proteccion-rutas` con boundary checks (repos ajenos y siblings `repo-evil` siguen bloqueados); el resto de hooks en DT-HOOKS-RAIZ-GIT.
+
+- **`node --test <directorio>` en Windows intenta ejecutar el directorio como test y falla en milisegundos sin correr nada** [caso real 2026-07-10: `node --test tests/ciclo-autonomo/` reportó 1 fail en 42ms cuando el glob equivalente corría 21 tests]: la duración es la delatora — <100ms para una suite que debería tardar segundos significa que el runner no encontró tests, no que fallaron. Fix: glob explícito entre comillas — `node --test "tests/ciclo-autonomo/*.test.js"`.
+
+- **El exit code de un pipeline es el del ÚLTIMO comando — verificar suites con `cmd | grep` enmascara fallos** [caso real 2026-07-09: `npm run test:all | grep ℹ | head` reportó "verde" durante horas sobre una suite que fallaba; el único runner sin máscara fue el `prepublishOnly` del usuario, que tumbó el publish]: en bash, `a | b` sale con el código de `b` (grep=0 si matcheó algo). Patrón correcto para verificar comandos largos: `cmd > /tmp/x.log 2>&1; echo "exit=$?"` y decidir por el exit explícito; el grep va DESPUÉS, sobre el log. Alternativa: `set -o pipefail` al inicio del script. Aplica a todo: suites, builds, linters, gates.
+
+- **Matriz de canales de hooks — stderr con exit 0 es un canal INVISIBLE** [origen: check-update 2026-07-08, el aviso de nuevas versiones se emitió al vacío desde su creación]: en Claude Code, el canal correcto depende del exit code. **exit 0 (éxito)**: solo el stdout llega — como contexto del turno en UserPromptSubmit/SessionStart (o `hookSpecificOutput.additionalContext`); el stderr no lo lee nadie. **exit 2 (bloqueo)**: solo el stderr llega al modelo con la razón del bloqueo; stdout con exit 2 = bloqueo ciego (regla ya conocida, L1 #4 de APRENDIZAJES). Anti-patrón resultante: "hook que funciona perfecto y nadie ve" — todo aviso al usuario desde un hook exitoso DEBE ir a stdout, idealmente con instrucción explícita ("INFORMA AL USUARIO...") para que el modelo lo retransmita. Verificación: correr el hook a mano con un flag de forzado y confirmar en qué canal aparece el mensaje.
+
+- **El payload de los hooks PostToolUse NO trae `model` ni `usage` — pero `transcript_path` SÍ viene y contiene ambos**: un hook que necesite el contexto real o el modelo activo no debe estimarlos por heurística (un contador de invocaciones × tokens promedio divergió >2x del contexto real y nunca se corregía tras `/compact` — caso swl-ses 2026-07-03). Fuente exacta: leer la cola del JSONL de `transcript_path`, tomar el último mensaje `type: 'assistant'` del hilo principal (filtrar `isSidechain: true` — los subagentes tienen OTRO context window) y sumar `usage.input_tokens + cache_read_input_tokens + cache_creation_input_tokens` = tamaño exacto del contexto de esa llamada; `message.model` da el modelo real. Tras `/compact` la siguiente entrada refleja el contexto compactado — la medición se auto-corrige sin resets.
+- **`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ó.
+- **`child_process.spawn(cmd, args, { env: {} })` REEMPLAZA el env del padre con vacío, NO hereda** [CONFIRMADO 2026-05-18]: el cliente MCP de Claude Code (y el de Cursor) lee `mcpServers.X.env` del config JSON y lo pasa literal al spawn. Si la config tiene `"env": {}` explícito, el binario hijo arranca SIN ninguna variable de entorno del padre — rompe la herencia de apiKeys que viven en HKCU/registry. Síntoma: MCP server da `40101 Authorization required` aunque `setx OBSIDIAN_API_KEY` esté correcto en HKCU y curl con esa key responda HTTP 200 al plugin. Causa: Node `child_process.spawn` con `env: {}` ≠ sin `env` option. Solución: **OMITIR la clave `env` por completo en el JSON** (no dejarla vacía). Verificado empíricamente con `spawn(binario, [], { /* sin env */ })` → binario heredó `OBSIDIAN_API_KEY`; `spawn(binario, [], { env: {} })` → binario sin env. El patch SWL para Python (`scripts/lib/mcp_config.py::build_stdio_env`) merge `os.environ + overrides` para corregir el mismo síntoma en el lado Python.
+- **MCP server devuelve auth error con apiKey correcta en disco → el proceso vivo arrancó con apiKey vieja** [CONFIRMADO 2026-05-18]: aunque `~/.cursor/mcp.json` y `~/.claude/settings.json` tengan la apiKey actual del plugin, los procesos del binario MCP (ej. `mcp-obsidian.exe`) que ya están corriendo retuvieron la apiKey del momento de su spawn. Síntoma: actualizar JSONs no soluciona 40101. Solución: `taskkill /F /IM mcp-obsidian.exe /T` (Windows) o `pkill mcp-obsidian` (Unix) + **quit total del cliente parent** (Cursor.exe / claude.exe) — no basta reload de ventana. Al reabrir, el cliente respawnea el binario con env actual. Verificar con `ps -W | grep mcp-obsidian` que solo haya procesos con timestamp posterior al reinicio.
+- **Cursor y Claude Code CLI dentro de Cursor son clientes MCP DISTINTOS con procesos independientes** [CONFIRMADO 2026-05-18]: cuando se ejecuta Claude Code CLI en una terminal embebida de Cursor, hay DOS procesos del binario MCP corriendo simultáneamente — uno por cliente. Cada uno lee SU PROPIA config: Cursor lee `~/.cursor/mcp.json`, Claude Code CLI lee `~/.claude/settings.json` + `<proyecto>/.claude/settings.local.json`. Una apiKey actualizada en uno no propaga al otro. Síntoma observado: el agente AI de Cursor responde MCP OK pero Claude Code CLI da 40101 (o viceversa). Solución: usar variable de entorno persistente del SO (`setx OBSIDIAN_API_KEY` → HKCU\Environment) como single source of truth y dejar configs JSON sin clave `env` para heredar del padre. Cada regeneración de apiKey requiere un solo `setx` + reiniciar Cursor (que reinicia ambos clientes).
+
+---
+
+## Integración con SWL
+
+Componentes SWL que cubren necesidades de harness: `/swl:compactar`,
+`/swl:checkpoint`, `/swl:status dashboard`, `/swl:status metricas`, `/swl:modelo`,
+`/swl:contexto`, hook `preservar-estado-pre-compact.js` (PreCompact),
+`/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:status metricas`)