sdd-es 2.0.0 → 2.5.0

package/skills/interpretar-idea/SKILL.md

@@ -0,0 +1,254 @@
+---
+description: Convierte una idea en texto libre a un IR (Interpreted Requirement) JSON validado. Trabaja en 2 fases - razonamiento libre + extracción JSON. Lee .sdd/descubrimiento.md si existe.
+model: claude-opus-4-8
+allowed-tools: Read, Write
+---
+
+# Skill: Interpretar Idea → IR
+
+## Propósito
+
+Tomar la idea del usuario (más el contexto de discovery si existe) y convertirla en un **IR JSON válido** que alimente el pipeline FORGE. Sin que el usuario tenga que pensar en estructura, campos, o intención.
+
+---
+
+## Contexto que debes leer primero
+
+Antes de empezar, lee:
+
+```bash
+cat .sdd/descubrimiento.md 2>/dev/null || echo "SIN_DISCOVERY"
+```
+
+Si existe `descubrimiento.md`, úsalo como contexto adicional para enriquecer el IR.
+
+---
+
+## Flujo en 2 fases
+
+### FASE A — Razonamiento libre (sin JSON)
+
+Analiza la idea en prosa libre. **No generes JSON todavía.** Solo piensa:
+
+```
+Analizando: "[idea del usuario]"
+Contexto de discovery: [resumen de descubrimiento.md si existe]
+
+ANÁLISIS:
+- Tipo de producto: [web app / mobile / api / cli / saas / other]
+- Usuarios principales: [quién lo usa]
+- Problema que resuelve: [qué dolor alivia]
+- Features core (los más críticos para V1): [lista priorizada]
+- Features secundarios (futuro): [lista]
+- Restricciones evidentes: [técnicas, de negocio, de tiempo]
+- Ambigüedades detectadas: [qué no está claro]
+- Asunciones que haré: [cómo resuelvo las ambigüedades]
+- Confianza estimada: [0.0–1.0] por qué
+```
+
+Sé honesto con la confianza. Una idea vaga tiene confidence 0.5–0.65. Una idea clara tiene 0.8–0.9. Nunca 1.0.
+
+### FASE B — Extracción a IR JSON
+
+Solo después del análisis, extrae el IR JSON:
+
+```json
+{
+  "id": "ir-[slug-del-producto]-001",
+  "created_at": "[ISO timestamp]",
+  "raw_input": "[idea literal del usuario]",
+  "confidence": [0.0–1.0],
+
+  "product": {
+    "name": "[Nombre descriptivo del producto]",
+    "type": "[saas|mobile|web|api|cli|other]",
+    "tagline": "[Una línea que describe el valor en <10 palabras]",
+    "value_proposition": "[Por qué existe este producto, en 1 oración]",
+    "target_users": "[Quién lo usa, en lenguaje natural]"
+  },
+
+  "features": {
+    "core": [
+      "[Feature 1 — lo más esencial del MVP]",
+      "[Feature 2]",
+      "[Feature 3]",
+      "[Feature 4 si aplica]",
+      "[Feature 5 si aplica — máximo 5]"
+    ],
+    "nice_to_have": [
+      "[Feature futuro 1]",
+      "[Feature futuro 2]"
+    ]
+  },
+
+  "constraints": {
+    "budget": "[bajo|medio|alto|ilimitado|null]",
+    "timeline": "[ASAP|semanas|meses|flexible|null]",
+    "team_size": "[1 persona|equipo pequeño|equipo grande|null]",
+    "tech_preference": "[React|Python|Node|null — null si no mencionó]"
+  },
+
+  "assumptions": [
+    "[Asunción 1 — lo que decidiste sin que el usuario lo dijera]",
+    "[Asunción 2]"
+  ],
+
+  "ambiguities": [
+    {
+      "field": "[campo afectado]",
+      "issue": "[qué no estaba claro]",
+      "resolution": "[cómo lo resolviste]"
+    }
+  ],
+
+  "requires_clarification": [true|false],
+  "questions_for_user": [
+    "[Pregunta 1 si confidence < 0.7 — máximo 1 pregunta]"
+  ]
+}
+```
+
+---
+
+## Reglas de validación del IR
+
+El IR es válido si:
+
+- ✅ `product.type` es uno de: `saas`, `mobile`, `web`, `api`, `cli`, `other`
+- ✅ `features.core` tiene **2–5 items** (no 0, no 6+)
+- ✅ `confidence` está entre `0.0` y `1.0`
+- ✅ `assumptions[]` es un array (puede estar vacío)
+- ✅ `ambiguities[]` es un array (puede estar vacío)
+- ✅ Si `confidence < 0.7` → `requires_clarification: true` y `questions_for_user` tiene **máximo 1 pregunta**
+
+Si el IR no cumple alguna regla, corrígelo antes de guardarlo.
+
+---
+
+## Cuándo preguntar vs. asumir
+
+**Asumir siempre** cuando:
+- El usuario no mencionó tecnología → asumir `tech_preference: null`
+- El usuario no mencionó presupuesto → asumir `budget: null`
+- Es obvio por el contexto (ej: "app de citas para peluquería" → `type: web`)
+
+**Preguntar solo cuando**:
+- `confidence < 0.7` (la idea es genuinamente ambigua)
+- Y solo **1 pregunta**, la más crítica para desambiguar
+
+**Ejemplos de preguntas válidas**:
+- "¿Es para tú negocio personal o para múltiples negocios?"
+- "¿Los usuarios pagan por el servicio o es gratuito?"
+
+**Ejemplos de preguntas inválidas** (nunca hacer):
+- "¿Qué tecnología prefieres?" (técnico, no relevante para el IR)
+- "¿Cuántas funcionalidades quieres?" (abierto, sin respuesta útil)
+- "¿Tienes algún prototipo?" (fuera de scope)
+
+---
+
+## Output final
+
+### Si `confidence ≥ 0.7`:
+
+1. Muestra el IR en formato legible:
+
+```
+═══════════════════════════════════════════
+🎯 TU IDEA INTERPRETADA
+═══════════════════════════════════════════
+
+Producto: [product.name]
+Tipo:     [product.type en español: "aplicación web" / "app móvil" / etc.]
+Para:     [target_users]
+
+Qué hace: [value_proposition]
+
+Features del MVP:
+  ✦ [core[0]]
+  ✦ [core[1]]
+  ✦ [core[2]]
+  [... hasta 5]
+
+Para más adelante:
+  · [nice_to_have[0] si existe]
+
+Confianza: [██████████░░] [confidence*100]%
+
+Asunciones que hice:
+  → [assumption[0]]
+  → [assumption[1] si existe]
+
+[Si hay ambiguities:]
+Preguntas resueltas:
+  ✓ [ambiguity[0].issue] → [ambiguity[0].resolution]
+
+═══════════════════════════════════════════
+¿Es esto lo que querías?
+  Escribe "sí" para continuar al diseño
+  Escribe "no, cambia [qué]" para corregir
+═══════════════════════════════════════════
+```
+
+2. Guarda en `.sdd/ir.json` (solo tras confirmación del usuario)
+3. Guarda el análisis de Fase A en `.sdd/ir-analysis.md`
+
+### Si `confidence < 0.7`:
+
+1. Muestra la pregunta de clarificación antes de continuar:
+
+```
+Antes de continuar, necesito una aclaración:
+
+[questions_for_user[0]]
+```
+
+2. Espera la respuesta
+3. Incorpora la respuesta al análisis
+4. Re-genera el IR con la nueva información
+5. Ahora confidence debería ser ≥ 0.7 → muestra el IR y pide confirmación
+
+---
+
+## Guardar archivos
+
+### `.sdd/ir.json`
+El IR JSON completo. Se guarda solo después de que el usuario confirme.
+
+### `.sdd/ir-analysis.md`
+El análisis de Fase A. Se guarda siempre (útil para auditoría).
+
+```markdown
+# IR Analysis — [product.name]
+
+**Fecha**: [timestamp]
+**Idea original**: [raw_input]
+
+## Análisis libre (Fase A)
+
+[Texto completo del análisis en prosa]
+
+## IR generado (Fase B)
+
+```json
+[IR JSON completo]
+```
+
+## Validación
+
+- confidence: [valor]
+- requires_clarification: [true/false]
+- errores de validación: [lista o "ninguno"]
+```
+
+---
+
+## Casos de prueba esperados
+
+| Idea | Confidence esperado | requires_clarification |
+|------|---------------------|----------------------|
+| "App para dentistas que gestionen citas" | 0.82–0.88 | false |
+| "Quiero algo para mis pedidos" | 0.55–0.65 | true |
+| "Plataforma de e-commerce con pagos, inventario y envíos" | 0.80–0.88 | false |
+| "No sé bien, algo para organizar cosas" | 0.40–0.55 | true |
+| "API REST para un sistema de autenticación con JWT y refresh tokens" | 0.88–0.95 | false |

package/skills/memory-compactor/SKILL.md

@@ -0,0 +1,114 @@
+---
+description: Comprime los archivos .sdd/memoria/agente-*.md cuando superan 80 entradas o 50KB. Elimina duplicados (misma ruta, fecha distinta — conserva la más reciente) y aplica el diccionario caveman de compresion-tokens (Nivel Full). Produce backup .original antes de comprimir.
+model: claude-haiku-4-5-20251001
+allowed-tools: Read, Write, Bash
+---
+
+# Skill: Memory Compactor
+
+## Propósito
+
+Los archivos de memoria de agentes crecen indefinidamente a lo largo de proyectos largos. Una memoria de 200 entradas consume ~30KB de ventana de contexto en cada invocación del agente — contexto que podría usarse para la tarea real. Esta skill comprime esos archivos sin perder las decisiones clave.
+
+**Cuándo ejecutar:**
+- Cuando el hook `agent-memory.js` emite: `⚠️ Memoria de {agente} supera 50KB`
+- Cuando `/sdd.optimizar memoria` detecta archivos por encima del umbral
+- Manualmente si el agente empieza a ignorar instrucciones (señal de contexto saturado)
+
+---
+
+## PASO 1 — Detectar archivos que superan el umbral
+
+```bash
+# Listar archivos de memoria con su tamaño
+ls -la .sdd/memoria/agente-*.md 2>/dev/null || echo "SIN_ARCHIVOS_MEMORIA"
+
+# Contar entradas por archivo (cada entrada empieza con "## ")
+for f in .sdd/memoria/agente-*.md; do
+  [ -f "$f" ] || continue
+  entradas=$(grep -c "^## " "$f" 2>/dev/null || echo 0)
+  bytes=$(wc -c < "$f" 2>/dev/null || echo 0)
+  echo "$f: $entradas entradas, $bytes bytes"
+done
+```
+
+**Umbral de intervención:** >80 entradas O >50KB. Si ningún archivo supera el umbral, reportar "✅ Memorias dentro del umbral — no se requiere compresión" y terminar.
+
+---
+
+## PASO 2 — Para cada archivo que supera el umbral
+
+### 2a. Crear backup
+
+```bash
+cp .sdd/memoria/agente-{nombre}.md .sdd/memoria/agente-{nombre}.md.original
+```
+
+### 2b. Leer el archivo completo
+
+Parsear línea a línea. Cada entrada tiene este formato:
+```markdown
+## 2026-06-13 — ruta/del/archivo.md
+> resumen de la acción tomada
+```
+
+### 2c. Eliminar duplicados
+
+Agrupar entradas por `archivo` (la parte después del `—` en el encabezado `##`). De cada grupo, conservar **solo la entrada más reciente** (la de fecha más alta). Las fechas están en formato ISO 8601 `YYYY-MM-DD` — ordenar lexicográficamente es suficiente.
+
+**Ejemplo:**
+```
+## 2026-06-01 — .sdd/especificaciones/auth/spec.md  ← ELIMINAR (más antigua)
+## 2026-06-10 — .sdd/especificaciones/auth/spec.md  ← CONSERVAR (más reciente)
+```
+
+### 2d. Aplicar compresión Nivel Full al cuerpo de cada entrada
+
+El diccionario completo vive en `{PLUGIN_DIR}/skills/compresion-tokens/SKILL.md`. No duplicar los pares aquí — leer la sección "Diccionario Nivel Full" de esa skill y aplicar los mismos 80+ reemplazos sobre el texto de cada línea `>`.
+
+**Patrones que NUNCA comprimir** (igual que en `compresion-tokens`):
+- Rutas de archivo (la parte después del `—` en `##`)
+- Código entre backticks
+- Nombres de variables, funciones, clases
+- URLs y comandos
+
+### 2e. Reescribir el archivo comprimido
+
+```markdown
+# Memoria del agente: {nombre}
+
+[Comprimido por memory-compactor el {fecha}. Backup en .original]
+Léelo al inicio de cada sesión para mantener continuidad entre conversaciones.
+
+---
+
+{entradas deduplicadas y comprimidas, ordenadas por fecha descendente}
+```
+
+---
+
+## PASO 3 — Reporte
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║        🧠 MEMORY COMPACTOR — Resultado                       ║
+╠══════════════════════════════════════════════════════════════╣
+║  AGENTE           | ANTES        | DESPUÉS      | REDUCCIÓN  ║
+║  ─────────────────┼──────────────┼──────────────┼─────────── ║
+║  {nombre}         | {N} entr.    | {M} entr.    | {%}%       ║
+║                   | {KB_antes}KB | {KB_desp}KB  |            ║
+╠══════════════════════════════════════════════════════════════╣
+║  Backups guardados en: .sdd/memoria/*.md.original            ║
+║  Para restaurar: cp agente-{nombre}.md.original agente-...   ║
+╚══════════════════════════════════════════════════════════════╝
+```
+
+---
+
+## Notas
+
+- Esta skill reutiliza el diccionario de `compresion-tokens` — no lo reinventa.
+- La deduplicación es la técnica más efectiva: en proyectos largos, el 40-60% de las entradas son re-escrituras del mismo archivo.
+- Nunca borrar el `.original` automáticamente — el usuario decide cuándo hacerlo.
+- Si un archivo tiene <20 entradas y <20KB, saltar silenciosamente aunque se haya invocado la skill.
+- Esta skill se invoca desde `/sdd.optimizar memoria` y desde `/sdd.comprimir memoria`.

package/skills/modo-guiado/SKILL.md

@@ -20,7 +20,7 @@ grep -q '"perfil": *"guiado"' .sdd/estado.json 2>/dev/null && echo GUIADO
 grep -q '^perfil: *guiado' .sdd/sdd.config.yaml 2>/dev/null && echo GUIADO
 ```
 
-## Reglas de comunicación (las 6 reglas)
+## Reglas de comunicación (las 8 reglas)
 
 1. **Sin jerga.** Nunca digas "endpoint", "schema", "ORM", "deploy", "lint", "CI". Di "dirección donde vive el dato", "estructura de la información", "guardar en disco", "publicar en internet", "revisión automática de calidad". Si un término técnico es inevitable, defínelo en la misma frase con una analogía.
 
@@ -34,6 +34,15 @@ grep -q '^perfil: *guiado' .sdd/sdd.config.yaml 2>/dev/null && echo GUIADO
 
 6. **Explica el resultado en términos de lo que el usuario puede hacer ahora.** Al terminar un paso: *"Ya puedes crear tareas y marcarlas como hechas. ¿Quieres que lo publiquemos en internet para usarlo desde el móvil?"* — no *"implementé el CRUD con 14 tests, cobertura 87%"*.
 
+7. **Pausar y explicar cuando hay confusión.** Si el usuario dice "no entiendo", "explícame", o "no sé qué significa eso", **pausa inmediatamente** y explica con una analogía del mundo real ANTES de continuar. No hagas jerga. Ejemplo:
+   - Usuario: "¿Qué es una base de datos?"
+   - Tú (❌ MAL): "Es un SGBD relacional que persiste datos en forma normalizada."
+   - Tú (✅ BIEN): "Piensa en una base de datos como una hoja de cálculo (como Excel). Guarda toda la información de tu proyecto — usuarios, productos, mensajes, etc. El sistema la usa para encontrar información rápidamente cuando la necesita."
+
+8. **Cierre explícito de cada fase.** Al final de cada FASE (especificar, planificar, implementar, verificar), explica exactamente qué puede hacer el usuario AHORA con lo que se construyó. Ejemplo:
+   - ❌ "Implementé el módulo de autenticación con JWT y bcrypt."
+   - ✅ "✅ Tu código está listo. Ahora puedes: (1) verlo en GitHub, (2) probarlo en internet, (3) cambiar algo si no te gusta, (4) invitar a otros a trabajar contigo."
+
 ## Cómo traducir los pasos del flujo
 
 | Paso técnico interno | Cómo lo nombras al usuario |
@@ -72,7 +81,8 @@ Si una verificación falla, NO digas "el test X falló con assertion error". Di:
 
 ## Cierre de cada interacción
 
-Termina siempre ofreciendo el siguiente paso como una acción en lenguaje natural, no como un comando:
+Termina siempre ofreciendo el siguiente paso como una acción en lenguaje natural, no como un comando. Usa la Regla 8 para enumerar explícitamente qué puede hacer el usuario ahora:
 
 > ✅ Ya está. Tu lista de tareas funciona.
+> Ahora puedes: (1) usarla ahora mismo, (2) invitar a otros a colaborar, (3) cambiar cómo se ve.
 > ¿Quieres que **la publique en internet** para usarla desde cualquier lado? (responde *sí*)

package/skills/observabilidad-consumo/SKILL.md

@@ -0,0 +1,164 @@
+---
+description: Lee .sdd/observabilidad/consumo.jsonl y genera un reporte de actividad de agentes — invocaciones por agente, archivos tocados, picos y señales de fan-out excesivo. Referencia cruzada con orquestacion-ptc y compresion-tokens.
+model: claude-haiku-4-5-20251001
+allowed-tools: Read, Bash
+---
+
+# Skill: Observabilidad de Consumo
+
+## Propósito
+
+Convertir el ledger de consumo en información accionable: ver cuántos agentes se activaron, qué archivos tocaron, en qué momentos hubo picos de actividad y si hay señales de fan-out excesivo que conviene corregir.
+
+El ledger es un proxy de magnitud (bytes escritos), no una facturación exacta de tokens — Claude Code no expone el conteo real de tokens al hook. Pero es suficiente para detectar patrones problemáticos.
+
+---
+
+## Lo que lees
+
+```bash
+# Ledger completo
+cat .sdd/observabilidad/consumo.jsonl 2>/dev/null || echo "SIN_LEDGER"
+
+# Conteo rápido de líneas
+wc -l .sdd/observabilidad/consumo.jsonl 2>/dev/null || echo "0"
+```
+
+---
+
+## Análisis que produces
+
+### 1. Resumen por agente
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) { console.log('Sin datos aún.'); process.exit(0); }
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const porAgente = {};
+for (const l of lineas) {
+  try {
+    const e = JSON.parse(l);
+    const a = e.agente || 'main';
+    if (!porAgente[a]) porAgente[a] = { invocaciones: 0, bytes: 0, archivos: new Set() };
+    porAgente[a].invocaciones++;
+    porAgente[a].bytes += e.bytes || 0;
+    porAgente[a].archivos.add(e.archivo);
+  } catch {}
+}
+
+console.log('AGENTE              | INVOC | BYTES  | ARCHIVOS ÚNICOS');
+console.log('-'.repeat(60));
+for (const [a, d] of Object.entries(porAgente).sort((x,y) => y[1].invocaciones - x[1].invocaciones)) {
+  console.log(\`\${a.padEnd(19)} | \${String(d.invocaciones).padStart(5)} | \${String(d.bytes).padStart(6)} | \${d.archivos.size}\`);
+}
+console.log('');
+console.log('Total eventos:', lineas.length);
+"
+```
+
+### 2. Detección de fan-out excesivo
+
+Umbrales por defecto (ajustables en `.sdd/sdd.config.yaml`):
+
+| Señal | Umbral | Acción sugerida |
+|-------|--------|-----------------|
+| >5 agentes distintos en una fase | Alto | Revisar si la orquestación PTC puede colapsar en menos agentes |
+| >20 invocaciones de un mismo agente | Medio | Revisar si el agente entra en loop o hace trabajo redundante |
+| >500 KB de bytes escritos totales | Informativo | Considerar comprimir memoria con `compresion-tokens` |
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) process.exit(0);
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const agentes = new Set();
+const invocPorAgente = {};
+let bytesTotal = 0;
+
+for (const l of lineas) {
+  try {
+    const e = JSON.parse(l);
+    const a = e.agente || 'main';
+    agentes.add(a);
+    invocPorAgente[a] = (invocPorAgente[a] || 0) + 1;
+    bytesTotal += e.bytes || 0;
+  } catch {}
+}
+
+const alertas = [];
+if (agentes.size > 5) alertas.push('⚠️  Fan-out alto: ' + agentes.size + ' agentes distintos activos');
+for (const [a, n] of Object.entries(invocPorAgente)) {
+  if (n > 20) alertas.push('⚠️  Agente en loop posible: ' + a + ' (' + n + ' invocaciones)');
+}
+if (bytesTotal > 500_000) alertas.push('ℹ️  Escritura alta: ' + Math.round(bytesTotal/1024) + ' KB — considera compresion-tokens');
+
+if (alertas.length === 0) {
+  console.log('✅ Sin alertas de fan-out');
+} else {
+  for (const a of alertas) console.log(a);
+}
+"
+```
+
+### 3. Picos de actividad (top 5 momentos)
+
+```
+node -e "
+const fs = require('fs');
+const path = '.sdd/observabilidad/consumo.jsonl';
+if (!fs.existsSync(path)) process.exit(0);
+
+const lineas = fs.readFileSync(path, 'utf8').trim().split('\n').filter(Boolean);
+const parsed = lineas.map(l => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
+
+// Agrupar por minuto
+const porMinuto = {};
+for (const e of parsed) {
+  const minuto = e.ts?.slice(0,16) || 'desconocido';
+  porMinuto[minuto] = (porMinuto[minuto] || 0) + 1;
+}
+
+const top = Object.entries(porMinuto).sort((a,b) => b[1] - a[1]).slice(0, 5);
+console.log('TOP 5 MINUTOS DE MAYOR ACTIVIDAD:');
+for (const [m, n] of top) console.log('  ' + m + '  →  ' + n + ' eventos');
+"
+```
+
+---
+
+## Formato del reporte completo
+
+```
+╔══════════════════════════════════════════════════════╗
+║         📊 CONSUMO DE AGENTES — SDD-ES               ║
+╠══════════════════════════════════════════════════════╣
+║  AGENTE              | INVOC | BYTES  | ARCHIVOS     ║
+║  [tabla generada]                                    ║
+╠══════════════════════════════════════════════════════╣
+║  ALERTAS DE FAN-OUT                                  ║
+║  [alertas o "✅ Sin alertas"]                        ║
+╠══════════════════════════════════════════════════════╣
+║  TOP MOMENTOS DE ACTIVIDAD                           ║
+║  [top 5 minutos]                                     ║
+╠══════════════════════════════════════════════════════╣
+║  RECOMENDACIONES                                     ║
+║  → Si fan-out alto: revisar skill orquestacion-ptc   ║
+║  → Si bytes altos:  ejecutar /sdd.comprimir          ║
+║  → Si loop agente:  revisar el agente con /sdd.estado║
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Notas
+
+- El ledger se escribe en tiempo real por el hook `agent-memory.js` (PostToolUse)
+- Los `bytes` miden el contenido de cada escritura — son un **proxy de magnitud**, no el consumo real de tokens del modelo
+- Para vaciar el ledger al inicio de una sesión nueva: `echo "" > .sdd/observabilidad/consumo.jsonl`
+- Cruzar con `orquestacion-ptc` para decidir cuándo paralelizar vs. serializar agentes
+- Cruzar con `compresion-tokens` para decidir cuándo comprimir los archivos `.sdd/memoria/`