sdd-es 2.0.0 → 2.5.0

package/docs/MEMORIA-Y-OBSERVABILIDAD.md

@@ -0,0 +1,237 @@
+# Memoria, Observabilidad y Optimización de Tokens en SDD-ES
+
+Este documento explica cómo SDD-ES mantiene continuidad entre sesiones (memoria por agente), cómo monitorizar el consumo de agentes sin depender del conteo de tokens del modelo, y cómo usar las nuevas técnicas de optimización de tokens (v2.5.0).
+
+---
+
+## 1. Memoria por agente
+
+### Qué es
+
+Cada agente del Grupo OPUS (arquitecto, asesor-datos, disenador-api, critico) tiene un archivo de memoria persistente en:
+
+```
+.sdd/memoria/agente-{nombre}.md
+```
+
+Este archivo crece automáticamente durante la sesión: cada vez que el agente escribe un archivo, el hook `PostToolUse` registra la fecha, el archivo modificado y un resumen del contenido.
+
+### Para qué sirve
+
+Claude Code no mantiene contexto entre sesiones. El archivo de memoria resuelve este problema: al inicio de una nueva sesión, el agente lee su archivo de memoria y recupera las decisiones tomadas en sesiones anteriores — qué arquitectura se eligió, qué restricciones aplican, qué se acordó con el usuario.
+
+### Cómo funciona el hook
+
+El hook `claude-hooks/agent-memory.js` se ejecuta como `PostToolUse` tras cada `Write` o `Edit`. Lee la variable de entorno `CLAUDE_AGENT_NAME` que Claude Code inyecta cuando hay un subagente activo, y si el agente es uno de los cuatro del Grupo OPUS, añade una entrada al archivo de memoria correspondiente.
+
+Desde v2.5.0, el hook también emite una alerta por stderr cuando la memoria de un agente supera 50KB:
+
+```
+⚠️  [agent-memory] Memoria de arquitecto supera 52KB — considera ejecutar /sdd.optimizar memoria
+```
+
+### Formato de una entrada de memoria
+
+```markdown
+## 2026-06-13 — .sdd/especificaciones/2026-06-13-auth/spec.md
+> # Especificación: Autenticación con magic link — Decisión: usar Resend para emails
+```
+
+### Cuándo leer la memoria
+
+Los agentes leen su archivo de memoria al inicio de cada invocación. No necesitas hacer nada manualmente: si el archivo existe, el agente lo lee.
+
+### Cuándo comprimir la memoria
+
+Cuando la memoria supera 80 entradas o 50KB, empieza a consumir ventana de contexto sin aportar valor (entradas antiguas del mismo archivo son redundantes). Usa:
+
+```
+/sdd.optimizar memoria
+```
+
+Esto invoca `memory-compactor`, que deduplica entradas del mismo archivo (conserva solo la más reciente) y aplica compresión caveman (Nivel Full de `compresion-tokens`). Siempre guarda un backup `.original`.
+
+---
+
+## 2. Ledger de consumo (observabilidad)
+
+### Qué es
+
+`.sdd/observabilidad/consumo.jsonl` es un archivo de líneas JSON (una por evento) que registra cada escritura de archivo por cualquier agente, incluyendo el agente principal. Se escribe en tiempo real por el mismo hook `agent-memory.js`.
+
+Ejemplo de una línea del ledger:
+
+```json
+{"ts":"2026-06-13T14:32:07.123Z","agente":"arquitecto","tool":"Write","archivo":".sdd/especificaciones/2026-06-13-auth/spec.md","bytes":4821}
+```
+
+### Campos
+
+| Campo | Descripción |
+|-------|-------------|
+| `ts` | Timestamp ISO 8601 del momento de escritura |
+| `agente` | Nombre del agente (`CLAUDE_AGENT_NAME`) o `"main"` si es la sesión principal |
+| `tool` | Herramienta usada: `Write`, `Edit`, `MultiEdit` |
+| `archivo` | Ruta del archivo modificado |
+| `bytes` | Tamaño en bytes del contenido escrito |
+
+### Limitación importante
+
+Los `bytes` miden el tamaño del contenido escrito en cada invocación — **no el consumo real de tokens del modelo**. Claude Code no expone el conteo de tokens al hook. Los bytes son un **proxy de magnitud**: escrituras grandes correlacionan con más trabajo, pero no son equivalentes a la facturación de la API.
+
+Para costos exactos, usa el dashboard de Anthropic Console o la API de usage.
+
+### Cómo usar el ledger
+
+```
+/sdd.estado consumo
+```
+
+Esto invoca `observabilidad-consumo` y produce:
+- Tabla de invocaciones y bytes por agente
+- Alertas de fan-out (>5 agentes distintos, >20 invocaciones de un mismo agente)
+- Top momentos de actividad por minuto
+
+### Vaciar el ledger entre sesiones
+
+```bash
+echo "" > .sdd/observabilidad/consumo.jsonl
+```
+
+---
+
+## 3. Técnicas de optimización de tokens (v2.5.0)
+
+### El comando unificado
+
+```
+/sdd.optimizar
+```
+
+Ejecuta el ciclo completo de 6 pasos: consumo → routing → compresión de memoria → auditoría de caché → presupuesto → reporte con acciones ordenadas por impacto.
+
+Subcomandos disponibles:
+
+| Subcomando | Qué hace |
+|---|---|
+| `/sdd.optimizar` | Ciclo completo |
+| `/sdd.optimizar tokens` | Solo effort-router + cache-audit |
+| `/sdd.optimizar memoria` | Solo memory-compactor |
+| `/sdd.optimizar presupuesto` | Solo token-budget |
+
+---
+
+### Técnica 1 — Effort routing (mayor impacto)
+
+La skill `effort-router` recomienda el modelo y nivel de esfuerzo correcto para cada agente según la fase actual. Evita pagar Opus cuando la tarea es mecánica.
+
+**Regla de oro:** si el agente toma una decisión que no se puede deshacer → Opus. Si ejecuta una decisión ya tomada → Sonnet o Haiku.
+
+| Grupo | Fases | Ahorro vs. Opus-en-todo |
+|---|---|---|
+| A — Opus siempre | especificacion, planificacion, analisis | 0% |
+| B — Sonnet suficiente | implementacion (backend/frontend), verificacion, qa | ~40% |
+| C — Haiku suficiente | tests, docs, deploy, retro | ~80% |
+
+Ahorro típico en una fase de `implementacion` completa: **~56%**.
+
+---
+
+### Técnica 2 — Compresión de memoria (previene degradación de contexto)
+
+La skill `memory-compactor` actúa sobre `.sdd/memoria/agente-*.md`:
+
+1. **Deduplica**: misma ruta modificada en fechas distintas → conserva solo la más reciente (reduce 40-60% en proyectos largos)
+2. **Comprime**: aplica el diccionario caveman de `compresion-tokens` (Nivel Full, 80+ pares de reemplazos) sobre el texto de cada entrada
+3. **Backup**: guarda `.original` antes de tocar nada
+
+Cuándo actúa: cuando hay >80 entradas O >50KB en algún archivo de memoria.
+
+---
+
+### Técnica 3 — Auditoría de caché
+
+La skill `cache-audit` detecta los 3 patrones que invalidan el prompt caching silenciosamente:
+
+| Invalidador | Severidad | Fix |
+|---|---|---|
+| Timestamps dinámicos en el system prompt (`2026-06-13`) | Alta | Mover al final del prompt, en bloque separado |
+| UUIDs / IDs de sesión embebidos en el prompt | Alta | Pasar como argumento, no como parte del system prompt |
+| Contenido JSONL (`consumo.jsonl`) embebido en el prompt | Media | Leer con tool `Read` cuando se necesite |
+
+El prompt caching reduce hasta un 90% el costo de tokens de entrada para bloques estables. Un solo invalidador en el sistema prompt anula el beneficio completo.
+
+---
+
+### Técnica 4 — Presupuesto por fase
+
+La skill `token-budget` proyecta el costo relativo de las fases restantes y recomienda cuándo usar PTC paralelo vs. serial. Si hay historial en `consumo.jsonl`, calibra los pesos con la velocidad real de la sesión.
+
+Regla de paralelización (de `orquestacion-ptc`):
+
+| Tareas pendientes | Estrategia | Ahorro estimado |
+|---|---|---|
+| 1-2 | Serial directo | — |
+| 3-5 independientes | PTC paralelo | ~70% |
+| 6-10 independientes | PTC en 2 lotes | ~65% |
+| Con dependencias | Serial (respetar grafo) | — |
+
+---
+
+## 4. Cómo controlar los agentes con estos datos
+
+### Detectar paralelización innecesaria
+
+Si el ledger muestra >5 agentes activos en una sola fase, revisar `orquestacion-ptc`. Si los agentes se bloquean entre sí (uno necesita el output del otro), paralelizarlos desperdicia tokens.
+
+Señal del ledger: muchos agentes distintos con pocas invocaciones cada uno → fan-out excesivo.
+
+### Detectar agentes en loop
+
+Si un agente tiene >20 invocaciones en el ledger de una sesión, está probablemente en un ciclo de auto-corrección.
+
+Solución: `/sdd.estado agentes` y verificar condiciones de salida claras.
+
+### Detectar memoria que conviene comprimir
+
+La alerta del hook (`⚠️ Memoria supera 50KB`) es la señal principal. También visible desde `/sdd.optimizar`.
+
+---
+
+## 5. Arquitectura del sistema (v2.5.0)
+
+```
+claude-hooks/
+  agent-memory.js          ← Hook PostToolUse (Write/Edit/MultiEdit)
+                             → .sdd/memoria/agente-{nombre}.md  (4 agentes OPUS)
+                             → .sdd/observabilidad/consumo.jsonl (todos los agentes)
+                             → stderr: alerta si memoria supera 50KB
+
+skills/
+  observabilidad-consumo/  ← Lee consumo.jsonl, produce reporte, detecta fan-out
+  effort-router/           ← Routing Haiku/Sonnet/Opus por fase (v2.5.0)
+  memory-compactor/        ← Deduplicación + compresión de .sdd/memoria/ (v2.5.0)
+  cache-audit/             ← Detecta invalidadores silenciosos de caché (v2.5.0)
+  token-budget/            ← Proyecta costo por fase + recomendación PTC (v2.5.0)
+  compresion-tokens/       ← Diccionario caveman — reutilizado por memory-compactor
+  orquestacion-ptc/        ← Criterios PTC — reutilizados por token-budget
+
+commands/
+  sdd.estado.md            ← /sdd.estado consumo
+  sdd.optimizar.md         ← Ciclo completo de optimización (v2.5.0)
+  sdd.comprimir.md         ← /sdd.comprimir memoria → memory-compactor
+```
+
+---
+
+## 6. Tabla completa de skills de eficiencia
+
+| Skill | Qué hace | Cuándo usarla |
+|-------|----------|---------------|
+| `observabilidad-consumo` | Reporte del ledger JSONL | Siempre, o desde `/sdd.estado consumo` |
+| `effort-router` | Recomienda Haiku/Sonnet/Opus por fase | Al inicio de cada fase o desde `/sdd.optimizar` |
+| `memory-compactor` | Deduplica y comprime `.sdd/memoria/` | Cuando hay alerta de 50KB o desde `/sdd.optimizar memoria` |
+| `cache-audit` | Detecta invalidadores de caché | Antes de `/sdd.implementar` en proyectos grandes |
+| `token-budget` | Proyecta costo de fases restantes | Antes de fases costosas (analisis, implementacion larga) |
+| `orquestacion-ptc` | Explica cuándo paralelizar agentes | Fan-out alto en el ledger |
+| `compresion-tokens` | Comprime cualquier archivo `.sdd/` | Memoria muy larga, specs verbosas |

package/docs/MODELOS.md

@@ -15,6 +15,9 @@
 | critico | **opus** | sonnet | haiku | Requiere razonamiento abstracto |
 | seguridad | **opus** | — | sonnet, haiku | Auditoría debe ser exhaustiva |
 | documentador | **sonnet** | haiku | opus (overkill) | Generación estructurada |
+| investigador | **sonnet** | opus (investigación profunda) | haiku | Análisis comparativo |
+| product-designer | **opus** | sonnet (MVPs) | haiku | Decisiones de producto irreversibles |
+| architecture-designer | **sonnet** | opus (stacks complejos) | haiku | Propuesta técnica estructurada |
 
 ## Filosofía
 

package/docs/QUE-PASA-SI-FALLA.md

@@ -0,0 +1,404 @@
+# ¿Qué Pasa Si Algo Sale Mal? Guía de Recuperación
+
+Este documento responde a las preguntas más comunes de usuarios no-técnicos cuando algo no sale como esperaban.
+
+---
+
+## Premisa: Tu código está **siempre seguro**
+
+Antes de cualquier respuesta, recuerda esto:
+
+✅ Tu código está guardado en GitHub (historial completo)
+✅ Cada cambio se registra (puedes ver quién cambió qué y cuándo)
+✅ Puedes volver a una versión anterior en cualquier momento (sin perder nada)
+
+---
+
+## Escenario 1: "El deploy falló — mi app no está en internet"
+
+### ¿Por qué pasó?
+
+```
+Vercel rechazó el código porque:
+→ Falta una variable de entorno
+→ Un archivo obligatorio no se generó
+→ El código tiene un error que no detectamos en pruebas
+```
+
+### ¿Qué hago?
+
+**Opción A: Reintentar** (si fue un error pasajero)
+
+```
+Claude responde:
+"Voy a intentar publicar de nuevo..."
+
+[Reintentos automáticos con espera]
+```
+
+**Opción B: Arreglar el código**
+
+```
+Si el error es técnico (variable faltante, etc.):
+
+Tú dices: "Cambio X cosa"
+Claude: "¿Qué cambias?"
+Tú: "Agrega soporte para pagos"
+
+Claude:
+1. Edita el código
+2. Prueba de nuevo
+3. Intenta publicar
+
+Tu versión anterior sigue en GitHub → sin miedo de cambiar
+```
+
+**Opción C: Esperar y intentar después**
+
+```
+Tú dices: "Dejar para después"
+
+Claude:
+✅ Tu código está seguro en GitHub
+✅ Puedes intentar publicar mañana
+✅ Nada se perdió
+```
+
+---
+
+## Escenario 2: "Cambié de idea a mitad del proceso"
+
+### Caso: Empezamos a construir, pero quiero otra cosa
+
+**Ejecuta `/sdd.constitucion` de nuevo:**
+
+```
+Claude detecta: "Ya hay una constitución"
+
+¿Quieres actualizar los principios?
+
+Tú: "Sí, cambio X"
+
+Claude:
+1. Actualiza la constitución
+2. Carga la especificación anterior
+3. ¿Modifico la especificación también?
+```
+
+**Lo que NO se pierde:**
+
+```
+✅ Especificación anterior (en GitHub)
+✅ Plan anterior (en GitHub)
+✅ Código que se construyó (en GitHub — rama anterior)
+
+Tú empiezas una nueva rama con los cambios.
+Si cambias de idea de vuelta, la anterior sigue disponible.
+```
+
+---
+
+## Escenario 3: "Publiqué pero después quiero cambiar algo"
+
+### Opción A: Cambio rápido (antes de compartir)
+
+```
+Tú dices: "Cambio el color del botón"
+
+Claude:
+1. Edita el código
+2. Prueba
+3. Publica la nueva versión (3 minutos)
+
+Usuarios no notan nada (refresca la página y ven la versión nueva)
+```
+
+### Opción B: Cambio importante (que afecta datos)
+
+```
+Tú dices: "Quiero agregar una nueva pregunta al formulario"
+
+Claude:
+1. Actualiza la especificación
+2. Genera un plan
+3. Pide tu aprobación
+4. Construye
+5. Prueba
+6. Publica
+
+[Igual que la primera vez, pero más rápido porque ya tiene contexto]
+```
+
+### Opción C: "Me arrepiento — vuelvo a la versión anterior"
+
+```
+Tú dices: "Vuelve a cómo estaba hace 2 horas"
+
+Claude:
+1. Ve a GitHub
+2. Encuentra ese commit
+3. Publica esa versión
+
+Tu sitio está igual que antes. Sin pérdida de datos.
+```
+
+---
+
+## Escenario 4: "Mi cliente dice que algo no funciona"
+
+### Paso 1: Reproducir el problema
+
+```
+Tú dices: "Mi cliente dice que X no funciona"
+
+Claude:
+1. Prueba el sitio en vivo
+2. Intenta reproducir el problema
+3. Pregunta: "¿Qué exactamente hizo tu cliente?"
+```
+
+**Ejemplo:**
+
+```
+Tú: "Mi cliente dice que el formulario no calcula el precio"
+
+Claude:
+"¿A qué tipo de proyecto selecciona?"
+Tú: "Logo simple"
+
+Claude:
+"¿Cuántas revisiones elige?"
+Tú: "Normal"
+
+[Claude llena el formulario con esos datos]
+
+Claude:
+"Aquí veo el problema: el precio dice $200, pero debería ser $300"
+```
+
+### Paso 2: Identificar la causa
+
+```
+Claude diagnostica:
+
+❌ Error de cálculo (la fórmula está mal)
+❌ Falta una opción (ej: urgencia 24 horas)
+❌ Base de datos no guarda bien los datos
+✅ Problema del navegador del cliente (caché viejo)
+```
+
+### Paso 3: Arreglar
+
+**Si es cálculo incorrecto:**
+
+```
+Tú: "El precio está mal"
+
+Claude:
+"¿Cuál debería ser el precio correcto para logo + normal?"
+Tú: "$400"
+
+Claude:
+1. Edita la fórmula
+2. Prueba con diferentes opciones
+3. Publica
+
+Listo. Tu cliente verá el precio correcto.
+```
+
+**Si es caché del navegador:**
+
+```
+Claude:
+"Dile a tu cliente que actualice la página (Ctrl+F5 o Cmd+Shift+R)"
+
+Eso borra la copia antigua del sitio de su navegador
+y carga la versión nueva.
+```
+
+---
+
+## Escenario 5: "¿Qué pasa si GitHub desaparece?"
+
+### Respuesta: No es realista, pero aquí está el plan
+
+```
+GitHub es propiedad de Microsoft. Es tan importante como AWS o Google.
+La probabilidad de que desaparezca es 0.001%.
+
+Pero si quieres dormir tranquilo:
+
+1. Tu código está en Vercel también (servidor en vivo)
+2. Puedes hacer "backup" a tu computadora en cualquier momento
+   (comando: git clone https://github.com/tu-user/tu-repo)
+3. Puedes mover tu repo a GitLab o Gitea en 5 minutos
+```
+
+---
+
+## Escenario 6: "¿Qué pasa si Vercel cobra y no puedo pagar?"
+
+### Respuesta: No sucede sin advertencia
+
+```
+Vercel es gratis hasta 100GB de ancho de banda (datos descargados).
+
+Si algo cambia:
+1. Te lo avisan con 30 días de anticipación
+2. Tu sitio NO desaparece (sigue funcionando)
+3. Puedes mover a otro servidor gratis (Netlify, Railway, etc.)
+4. Tus datos en GitHub no se pierden
+
+Claude puede ayudarte a mover en 30 minutos.
+```
+
+---
+
+## Escenario 7: "¿Qué pasa si cambia mi requerimiento legal?"
+
+### Ejemplo: Necesito cumplir GDPR, HIPAA, etc.
+
+```
+Tú: "Mi cliente quiere que el sitio cumpla GDPR"
+
+Claude:
+1. Ejecuta /sdd.compliance automáticamente
+2. Identifica qué falta
+3. Genera un plan
+4. Pregunta: "¿Apruebo estos cambios?"
+5. Implementa
+
+Ejemplo de cambios:
+- Agregar "política de privacidad"
+- Permitir que usuarios descarguen sus datos
+- Encriptar datos sensibles
+- Otros cambios específicos
+```
+
+---
+
+## Escenario 8: "¿Qué pasa si alguien hackea mi sitio?"
+
+### Respuesta: SDD-ES lo previene
+
+```
+Durante el proceso:
+
+✅ El agente de seguridad revisó el código automáticamente
+✅ Se prueban ataques comunes (XSS, SQL injection, etc.)
+✅ Secretos (contraseñas, API keys) no están en el código
+✅ Validación de datos (usuario no puede inyectar código malicioso)
+
+Si algo pasara:
+
+1. GitHub registra quién cambió qué (auditoría completa)
+2. Puedes volver a una versión anterior en segundos
+3. Investigar qué pasó (historial de cambios)
+```
+
+---
+
+## Escenario 9: "¿Y si alguien lo copia?"
+
+### Respuesta: Depende del contexto
+
+```
+Casos:
+
+❌ Algo muy valioso (algoritmo secreto, datos únicos)
+   → Considera cerrar el repo (private en GitHub)
+   → Requiere autenticación para acceder al sitio
+
+✅ Algo público (herramienta útil, componente reutilizable)
+   → Está bien que la copien
+   → Agrega tu licencia (MIT: "úsalo gratis, dame crédito")
+```
+
+---
+
+## Escenario 10: "Pasó algo raro — no sé qué está mal"
+
+### Paso 1: Ejecutar el diagnóstico
+
+```
+Tú: "Algo no funciona bien"
+
+Claude:
+"Voy a revisar todo..."
+
+Ejecuta: /sdd.doctor
+
+Este comando verifica:
+✅ Código sintaxis correcta
+✅ Todos los archivos presentes
+✅ Base de datos conectada
+✅ Servidor respondiendo
+✅ Tests pasando
+✅ Sin secretos expuestos
+```
+
+### Paso 2: Obtener un reporte
+
+```
+Claude te muestra:
+
+DIAGNOSTICO:
+✅ Código bien
+✅ Tests pasando
+❌ Base de datos no conecta
+
+CAUSA PROBABLE:
+El archivo de base de datos se eliminó accidentalmente.
+
+SOLUCION:
+Voy a restaurar desde GitHub...
+```
+
+---
+
+## Resumen: No hay error que no se pueda arreglar
+
+| Problema | Tiempo | Reversible | Datos seguros |
+|----------|--------|-----------|----------------|
+| Deploy falló | 2 min reintentar | ✅ Sí | ✅ Sí (GitHub) |
+| Cambié de idea | 10 min refactor | ✅ Sí | ✅ Sí (ramas) |
+| Cliente reporta bug | 5 min fix + test | ✅ Sí | ✅ Sí (auditoria) |
+| GitHub desaparece | 1 hora mover | ✅ Sí | ✅ Sí (backup local) |
+| Vercel cobra extra | 30 min migrar | ✅ Sí | ✅ Sí (GitHub) |
+| Compliance nueva | 20 min auditar | ✅ Sí | ✅ Sí (reportes) |
+| Hackeo potencial | — | ✅ Sí (rollback) | ✅ Sí (GitHub audit) |
+
+---
+
+## Mantra: "Tu código está seguro, cualquier cambio es reversible"
+
+Esto no es verdad en 99% de las herramientas.
+
+**Con SDD-ES:**
+
+```
+GitHub    → historial completo (quién, qué, cuándo)
+Vercel    → roll-forward/rollback en 1 click
+Especificación → documento versionado
+Plan      → aprobado por ti, registrado
+
+No hay decisión que no puedas deshacer.
+```
+
+---
+
+## Última línea: Si necesitas ayuda
+
+```
+Tu proyecto tiene:
+
+📝 Especificación clara (qué debería hacer)
+📋 Plan técnico (cómo se construyó)
+📊 Cambios documentados (quién hizo qué)
+✅ Tests automáticos (qué funciona)
+🔒 Auditoría de seguridad (vulnerabilidades conocidas)
+
+Si algo está mal, Claude tiene TODA la información para arreglarlo.
+
+Sin necesidad de programar. Solo describir el problema.
+```