feat(episode): TRAZA_diagnstico-raz-causa-3-opciones-de-fix_S20260525.R31_XX.ops.2.hot_inf.in.cc.es.000.MGQ_J.PMCFK_E.SGNFD

Skill: NONE | Type: troubleshooting
Summary: EPISODIO 31 — ember_inner: Diagnóstico raíz causa + 3 opciones de fix permanente

episodes/TRAZA_diagnstico-raz-causa-3-opciones-de-fix_S20260525.R31_XX.ops.2.hot_inf.in.cc.es.000.MGQ_J.PMCFK_E.SGNFD.md

@@ -0,0 +1,50 @@
+---
+episode_id: "0a4f1af8-86ff-45fb-a140-f89ef2f565ef"
+puente_flat: "TRAZA_diagnstico-raz-causa-3-opciones-de-fix_S20260525.R31_XX.ops.2.hot_inf.in.cc.es.000.MGQ_J.PMCFK_E.SGNFD"
+session_code: "S20260525.DASHBOARD_GRAFICOS_EXPANSION"
+acto_dialogico: "informar"
+actor_flujo: "multi_actor"
+criticidad_aegis: "low"
+skill_dominante: "NONE"
+fase_proyecto: "operations"
+tipo_semantico: "troubleshooting"
+summary_one_line: "EPISODIO 31 — ember_inner: Diagnóstico raíz causa + 3 opciones de fix permanente"
+source_type: "claude_code"
+trust_boundary: "internal"
+created_at: "2026-05-26T04:01:48.302356+00:00"
+relectura_tagged: false
+forgejo_commit_sha: "pending"
+---
+
+# Diagnóstico raíz causa + 3 opciones de fix permanente
+
+> **R18 — sub-tema:** Por qué la frase *"File has not been read yet. Read it first before writing to it."* para mi flujo + 3 soluciones complementarias (workflow + Bash-direct + wrapper arquitectónico) + recomendación.
+
+## [R18.seccion1.I1] Diagnóstico empírico raíz causa
+
+★ Insight ─────────────────────────────────────
+**El error NO viene de nuestros hooks EMBER** (BLINDADAs/PASSPORT/VERIFY-FIRST). Viene del **Claude Code SDK runtime nativo**.
+
+**Mecanismo interno (caja negra del SDK):** el runtime mantiene un tracking "archivos leídos esta sesión via Read tool" + Edit tool verifica esa entrada antes de ejecutar. Si el archivo NO fue leído via Read tool en la sesión activa, Edit aborta con ese mensaje.
+
+**Casos que disparan el bug:**
+
+| Caso | Por qué falla | Frecuencia hoy |
+|------|---------------|----------------|
+| `cp` via Bash + Edit subsequent | `cp` no registra en tracking del SDK (no es Read tool) | Alta (PASO 5 ahora) |
+| Write + PostToolUse hook modifica archivo + Edit subsequent | hook PASSPORT/formatter cambia contenido — SDK invalida tracking | Alta (PASO 4 → PASO 5) |
+| Session resume + Edit a archivo del filesystem | nueva sesión sin Read previo | Media (post-compactación) |
+| Archivo creado por hook generator + Edit subsequent | el hook escribió, no Read tool | Baja (futuro Fase B) |
+
+**Por qué me "para el pensamiento":** cada Edit fallido obliga: (1) ejecutar Read overhead 50-200 líneas + (2) cambiar contexto mental + (3) reintentar Edit + (4) verificar resultado. Multiplicado por 5-10 ediciones/turno = drag cognitivo significativo + interrupción flujo iterativo del LLM probabilístico tratando converger al contrato.
+─────────────────────────────────────────────────
+
+## [R18.seccion2.T1] 3 opciones de fix permanente
+
+| Opción | Descripción | Costo implementación | Costo runtime | Cobertura bug |
+|--------|-------------|----------------------|----------------|----------------|
+| **A. Workflow Read-always post-create** | Adoptar patrón: post-Write o post-cp, SIEMPRE Read antes de Edit subsequent. Convertir en parte del flujo canónico (PROCEDENCIA PR-canónico) | Cero (regla mental) | ~100-200 tokens/Edit extra | 100% (cubre todos los casos) |
+| **B. Bash-direct sed/python para modificaciones post-create** | Bypass Edit tool entirely para archivos recién creados/copiados. Usar `sed -i` o `python -c` con `pathlib.write_text()`. Aprovecha VERIFY-FIRST GATE override flag para no bloquear | Bajo (override flag pattern ya existe) | ~50-100 tokens menos (no Read) | 90% (no funciona si VERIFY-FIRST bloquea) |
+| **C. Wrapper Python "create_with_edits"** | Fabricar utility `.claude/hooks/lib/atomic_create_with_edits.py` que combina Write + sed/replace en operación atómica + telemetría JSONL. Invokable via Bash desde Ember-CC-Local | Medio (~150 LOC + tests pytest) | Cero overhead post-fabricación | 100% (solución arquitectónica permanente) |
+
+## [R18.seccion3.P1] Mi inclinación razonada + qué la cambiaría