@saulwade/swl-ses 2.6.0 → 2.8.0

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

@@ -1,314 +1,315 @@
----
-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`)
+---
+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.7"
+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).
+- **Un comando encadenado con `&&` donde un paso intermedio es bloqueado por un hook de risk-scoring aborta TODO el resto en silencio** (caso real 2026-07-17): `rm -rf <dir-scratch> && git add .gitignore && git status` — el `rm -rf` fue bloqueado por el hook de risk-scoring (score 0.65 > umbral), y como bash corta la cadena `&&` en el primer fallo, el `git add .gitignore` nunca se ejecutó. El `git status` final tampoco corrió, así que no había señal inmediata de que el segundo paso se hubiera saltado — solo se detectó al revisar el estado real del working tree y notar que `.gitignore` seguía sin stage. Regla: cuando cualquier paso de una cadena `&&` puede ser bloqueado por un hook (destructivo, escritura fuera de scope, comando de alto riesgo), correr los pasos como llamadas Bash separadas — nunca asumir que los pasos posteriores corrieron solo porque el tool call "se completó".
+- **Un timeout de Bash en tu propia verificación NO es evidencia de que el fix falló**: tras corregir un bug de aislamiento en un motor de mutation testing (F32-T07), dos intentos de reproducir la corrida completa vía `node -e` con timeout de 2 y 5 minutos expiraron sin dar resultado — pero eso mide el tiempo de la corrida real (56 min para 2275 mutantes), no la corrección del fix. Tratar el timeout como "no pude confirmarlo, quizá sigue roto" habría sido un falso negativo. La verificación correcta ante un timeout: leer el diff exacto del fix, correr el test de regresión específico por una vía alternativa que no dependa del runner que dio timeout (aquí: `require()` + `--test-name-pattern` en vez de `node --test`), y correr la suite completa (rápida) en vez de forzar la reproducción lenta. Un timeout es una limitación del método de verificación elegido, no del artefacto verificado — cambiar de método antes de degradar la confianza en el fix.
+
+---
+
+## 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`)