sdd-es 2.0.0 → 2.6.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: opus
+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/mejorar-prompt/SKILL.md

@@ -0,0 +1,237 @@
+---
+description: Transforma un prompt vago en versión profesional siguiendo los 7 patrones
+  de Claude Code (Contexto · Tarea · Restricciones · Formato · Verificación). Detecta
+  si el prompt solicita algo fuera de la spec activa y advierte antes de continuar.
+model: sonnet
+allowed-tools: Read, Bash
+---
+
+# Skill: Mejorar Prompt
+
+## Propósito
+
+Un prompt vago produce resultados impredecibles. Claude Code toma decisiones discrecionales
+sobre alcance, enfoque y dependencias cuando las instrucciones son ambiguas. Esta skill
+cierra esa brecha: toma la intención del usuario y la convierte en un prompt profesional
+con los componentes necesarios para obtener resultados predecibles y dentro de la spec activa.
+
+---
+
+## Lo que lees primero
+
+Antes de reescribir el prompt, lee el estado del proyecto:
+
+```bash
+# Fase y feature activa
+cat .sdd/estado.json 2>/dev/null || echo "SIN_ESTADO"
+
+# Spec activa (si existe estado)
+SPEC_ID=$(cat .sdd/estado.json 2>/dev/null | grep -o '"spec_activa":"[^"]*"' | cut -d'"' -f4)
+[ -n "$SPEC_ID" ] && cat ".sdd/especificaciones/${SPEC_ID}/spec.md" 2>/dev/null | head -40
+```
+
+Si no existe `.sdd/estado.json`: continúa sin validación de scope. No inventes un estado.
+
+---
+
+## Los 7 patrones
+
+Identifica cuál de estos patrones aplica al prompt del usuario antes de reescribirlo:
+
+| # | Patrón | Cuándo aplica |
+|---|--------|---------------|
+| 1 | **Implementar feature** | "añade X", "crea Y", "implementa Z" |
+| 2 | **Depurar problema** | "no funciona", "hay un error", "falla cuando" |
+| 3 | **Refactorizar** | "reorganiza", "limpia", "extrae", "mejora la estructura" |
+| 4 | **Explorar proyecto** | "explícame", "cómo funciona", "qué hace", "analiza" |
+| 5 | **Escribir tests** | "testea", "añade pruebas", "cobertura" |
+| 6 | **Documentar** | "documenta", "escribe el README", "añade JSDoc" |
+| 7 | **Pedir justificación** | "por qué hiciste", "qué alternativas", "justifica" |
+
+---
+
+## Flujo de mejora
+
+### PASO 1 — Clasifica el prompt
+
+Lee el prompt del usuario. Identifica:
+- El **patrón** de los 7 que mejor aplica
+- La **intención concreta** (qué quiere lograr, no cómo lo dice)
+- Las **entidades** mencionadas (qué módulos, archivos, funciones afecta)
+
+### PASO 2 — Verifica el scope
+
+Si existe `.sdd/estado.json`:
+- Extrae la feature activa y la fase actual
+- Compara con lo que el prompt pide
+
+**Si el prompt está FUERA del scope:**
+```
+⚠️ Alerta de scope: "{lo que pide}" parece estar fuera de la spec activa ("{feature}").
+
+Opciones antes de continuar:
+1. Escribe /sdd.especificar para abrir una spec nueva
+2. Confirma explícitamente que esto forma parte de la feature actual
+
+No continuaré hasta recibir confirmación.
+```
+Detente aquí. No reescribas el prompt.
+
+**Si el prompt está DENTRO del scope o no hay spec activa:** continúa al PASO 3.
+
+### PASO 3 — Evalúa el prompt actual
+
+Cuenta cuántos de los 5 componentes ya están presentes:
+
+| Componente | ¿Presente? |
+|---|---|
+| Contexto (qué proyecto/stack/estado existe ya) | sí / no |
+| Tarea (qué hay que hacer exactamente, acotado) | sí / no |
+| Restricciones (qué no tocar, qué no instalar) | sí / no |
+| Formato (cómo quiere el resultado) | sí / no |
+| Verificación (cómo confirmar que funcionó) | sí / no |
+
+Si el prompt tiene **≥ 4 componentes**: responde "Este prompt ya está bien estructurado
+(X/5 componentes). Solo falta: [el que falta]." y detente.
+
+### PASO 4 — Construye la versión profesional
+
+Para los componentes faltantes, infiere el contenido a partir de:
+- El estado del proyecto (`.sdd/estado.json`, `package.json`, estructura de carpetas)
+- Las convenciones del proyecto (naming, testing framework, estructura de módulos)
+- El patrón detectado en PASO 1
+
+Aplica el esquema del patrón correspondiente:
+
+**Patrón 1 — Implementar feature:**
+```
+Contexto: [proyecto, stack, qué existe ya relevante para esta feature]
+
+Tarea: Implementa [feature] con estos requisitos:
+- [requisito concreto 1]
+- [requisito concreto 2]
+
+Restricciones:
+- [qué no cambiar]
+- [dependencias que no instalar]
+- [patrones del proyecto a respetar]
+
+Verificación: [tests a crear y ejecutar, o comando para comprobar]
+```
+
+**Patrón 2 — Depurar problema:**
+```
+Contexto: [qué estaba haciendo cuando ocurrió]
+
+Tarea: Tengo este error:
+[pegar el error completo con stack trace]
+Archivo: [archivo y línea si lo sabes]
+
+Formato: Antes de corregir nada:
+1. Identifica la causa raíz, no el síntoma
+2. Explica por qué ocurre
+3. Propón el fix y justifícalo
+4. ¿Qué más podría verse afectado?
+
+Verificación: Añade un test que reproduzca el bug antes del fix y pase después.
+```
+
+**Patrón 3 — Refactorizar:**
+```
+Contexto: [qué módulo y por qué refactorizarlo]
+
+Tarea: Refactoriza [archivo/módulo] para [objetivo concreto].
+
+Restricciones:
+- La API pública NO debe cambiar
+- Los tests existentes deben seguir pasando sin modificarlos
+- Sigue el patrón [patrón del proyecto]
+
+Formato: Antes de tocar código, muéstrame qué cambiarías y por qué.
+
+Verificación: Ejecuta todos los tests sin cambiarlos. Si alguno falla, el refactoring rompió algo.
+```
+
+**Patrón 4 — Explorar proyecto:**
+```
+Tarea: Analiza [proyecto/módulo] y responde:
+- [pregunta sobre estructura]
+- [pregunta sobre patrones]
+
+Formato: [resumen breve por pregunta + diagrama ASCII si aplica]
+
+Restricciones: No modifiques nada. Solo lectura.
+```
+
+**Patrón 5 — Escribir tests:**
+```
+Contexto: [qué módulo/servicio y qué hace]
+
+Tarea: Genera tests para [archivo]. Para cada función pública:
+- Un test del caso normal (happy path)
+- Un test de caso edge [ejemplos]
+- Un test de error [ejemplos]
+
+Restricciones: [framework de testing del proyecto]
+
+Verificación: Ejecuta los tests. Muéstrame la cobertura del archivo.
+```
+
+**Patrón 6 — Documentar:**
+```
+Contexto: [quién va a leer esta doc y para qué]
+
+Tarea: Genera documentación para [archivo/módulo/API] incluyendo:
+- [secciones necesarias]
+
+Formato: [Markdown, JSDoc, README, etc.]
+
+Verificación: Compara el resultado con el código real. Si falta algo, añádelo.
+```
+
+**Patrón 7 — Pedir justificación:**
+```
+Sobre [la implementación que acabas de hacer]:
+1. ¿Qué alternativas consideraste y por qué elegiste esta?
+2. ¿Qué trade-offs tiene tu decisión?
+3. ¿Qué podría fallar con este enfoque?
+4. ¿Qué harías diferente con más tiempo o a mayor escala?
+```
+
+### PASO 5 — Presenta el resultado
+
+Muestra la respuesta completa con esta estructura:
+
+```
+## Prompt original
+[lo que escribió el usuario, sin cambios]
+
+## Patrón detectado
+[nombre del patrón] — [una frase de por qué aplica este patrón]
+
+## Prompt profesional
+
+[versión mejorada completa, lista para copiar y pegar]
+
+## Por qué funciona
+- **Contexto:** [qué se añadió y por qué]
+- **Tarea:** [cómo se acotó y por qué]
+- **Restricciones:** [qué se protegió y por qué]
+- **Verificación:** [cómo cierra el ciclo]
+```
+
+---
+
+## Notas
+
+**Prompt ya profesional:** Si el usuario envía un prompt con ≥4 componentes, confírmalo
+y ofrece solo el componente que falta, sin reescribir lo demás.
+
+**Prompt ambiguo:** Si la intención no está clara (ej. "arregla el código"), pregunta
+una sola cosa antes de continuar: "¿Qué parte específica no funciona como esperabas?"
+
+**Sin proyecto SDD:** Si no existe `.sdd/`, omite la validación de scope y el componente
+de restricciones relacionado con la spec. Aún aplica los 4 componentes restantes.
+
+**Cadena de patrones:** Cuando la tarea implica varias etapas, sugiere la cadena natural:
+Explorar → Implementar → Tests → Justificar → Documentar. Un prompt por etapa.

package/skills/memory-compactor/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: memory-compactor
+model: claude-haiku-4-5
+description: Comprime archivos de memoria de agentes cuando superan umbral (>50KB)
+allowed-tools: Read, Write, Bash
+---
+
+# Skill: Memory Compactor
+
+**Propósito:** Comprimir automáticamente archivos de memoria de agentes (`.sdd/memoria/agente-*.md`) cuando superan 50KB, eliminando entradas duplicadas y aplicando técnicas de reducción de contexto.
+
+---
+
+## Cuándo Usar
+
+1. **Automático:** Hook `agent-memory.js` la dispara cuando memoria > 50KB
+2. **Manual:** Usuario ejecuta `/sdd.optimizar memoria` en proyectos largos
+
+---
+
+## Qué Hace
+
+### Deduplicación
+Elimina entradas duplicadas del mismo archivo.
+
+### Compresión por Caveman (Nivel Full)
+Aplica diccionario de reemplazos: `CREATE TABLE` → `CT`, `SELECT * FROM` → `SF`, etc.
+
+### Backup Automático
+Crea `.original.md` antes de comprimir.
+
+---
+
+## Output
+
+**Antes:** `.sdd/memoria/agente-arquitecto.md = 150KB (80 entradas)`
+
+**Después:** `.sdd/memoria/agente-arquitecto.md = 15KB (8 entradas únicas)`
+
+Mensaje: `✨ [auto-compress] arquitecto: 150KB → 15KB (10%)`
+
+---
+
+## Detalles Técnicos
+
+- Deduplicación por `## YYYY-MM-DD — filepath`
+- Reutiliza diccionario de `skills/compresion-tokens/SKILL.md`
+- Backup `.original.md` siempre
+- Performance: <100ms
+- Trigger automático >50KB en `agent-memory.js`
+
+---
+
+## API (Internal)
+
+```javascript
+triggerAutoCompresion(cwd, agente, memoriaFile)
+```
+
+Ejecuta compresión automáticamente cuando se excede umbral.
+
+---
+
+## Notas
+
+- Idempotente (ejecutar 2 veces = mismo resultado)
+- Nunca pierdes datos (backup existe siempre)
+- No interrumpe flujos (solo stderr messages)

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í*)