sdd-es 2.5.0 → 2.6.0

package/plantillas/job-story-mejorar-prompt.md

@@ -0,0 +1,107 @@
+---
+id: JS-PROMPT-001
+tipo: job-story
+estado: aprobada
+fecha: 2026-06-14
+versión: 1.0.0
+autor: SDD-ES
+---
+
+# Job Story — Mejorar Prompts con Claude Code
+
+## Historia principal
+
+**Cuando** estoy a punto de pedirle algo a Claude Code y no sé cómo formularlo con precisión,
+**quiero** una guía que transforme mi intención vaga en un prompt profesional paso a paso,
+**para** obtener resultados predecibles, manteniendo el trabajo dentro del plan de la spec activa.
+
+---
+
+## Contexto del problema
+
+Un prompt vago produce resultados impredecibles porque Claude toma decisiones discrecionales
+sobre el alcance, el enfoque y las dependencias. El mismo prompt puede generar desde un
+try-catch de 3 líneas hasta un sistema de logging con Winston, rotación de archivos y niveles
+de severidad — dependiendo del momento y el contexto de la sesión.
+
+La diferencia entre un resultado útil y uno que hay que descartar no está en Claude Code,
+está en la calidad de las instrucciones. Esta job story captura la necesidad de cerrar esa
+brecha de forma sistemática, sin depender de la experiencia del usuario.
+
+---
+
+## Criterios de Aceptación
+
+- **CA-001:** dado un prompt vago de 1-2 frases, la skill produce una versión profesional
+  con los 5 componentes (Contexto, Tarea, Restricciones, Formato, Verificación) cuando aplican
+- **CA-002:** la versión mejorada incluye siempre una restricción explícita sobre el alcance
+  de la spec activa (`No salgas de lo definido en .sdd/especificaciones/`)
+- **CA-003:** si el prompt solicita algo fuera de la fase o feature actual (según
+  `.sdd/estado.json`), la skill lo detecta y advierte antes de reescribir
+- **CA-004:** el output muestra la justificación de cada componente añadido, no solo el
+  prompt mejorado
+- **CA-005:** la skill se puede invocar con `/mejorar-prompt "texto del prompt vago"`
+- **CA-006:** si el prompt ya es profesional (tiene ≥4 de los 5 componentes), la skill lo
+  confirma y no reescribe innecesariamente
+
+---
+
+## Escenarios BDD
+
+### Escenario 1 — Prompt de implementación vago
+
+```
+Dado:  el usuario escribe "añade autenticación"
+Cuando: invoca /mejorar-prompt "añade autenticación"
+Entonces: obtiene una versión profesional con:
+  - Contexto del stack actual (Express + TypeScript, endpoints existentes)
+  - Tarea acotada (qué tipo de autenticación, qué endpoints proteger)
+  - Restricciones (no romper endpoints existentes, no instalar dependencias no aprobadas)
+  - Verificación con tests que cubran el happy path y el rechazo de tokens inválidos
+Y: cada componente va acompañado de una línea explicando por qué se añadió
+```
+
+### Escenario 2 — Prompt fuera de spec
+
+```
+Dado:  la spec activa en .sdd/estado.json es "login con email"
+  Y:   el usuario escribe "añade un sistema de pagos con Stripe"
+Cuando: invoca /mejorar-prompt
+Entonces: la skill emite una advertencia:
+  "⚠️ 'pagos con Stripe' parece estar fuera de la spec activa (login con email).
+   Para continuar tienes dos opciones:
+   1. Escribe /sdd.especificar para abrir una nueva spec de pagos
+   2. Confirma que este cambio sí forma parte de la feature actual"
+Y: no reescribe el prompt hasta recibir confirmación
+```
+
+### Escenario 3 — Prompt de debug vago
+
+```
+Dado:  el usuario escribe "no funciona el login"
+Cuando: invoca /mejorar-prompt
+Entonces: la skill detecta el patrón "depurar problema" y produce:
+  - Contexto: qué estaba haciendo cuando falló
+  - Tarea: el error exacto (pegar stack trace) y el archivo/línea
+  - Formato: "antes de corregir: (1) causa raíz (2) por qué ocurre (3) fix propuesto"
+  - Verificación: test que reproduce el bug antes del fix y pasa después
+```
+
+### Escenario 4 — Prompt ya profesional
+
+```
+Dado:  el usuario escribe un prompt con contexto, tarea, restricciones y verificación
+Cuando: invoca /mejorar-prompt
+Entonces: la skill responde "Este prompt ya tiene 4/5 componentes. Está bien estructurado."
+  Y opcionalmente sugiere el único componente que falta (si hay alguno)
+  Y no reescribe el prompt
+```
+
+---
+
+## Notas de implementación
+
+- La skill vive en `skills/mejorar-prompt/SKILL.md`
+- El agente que la ejecuta es `sonnet` (balance razonamiento / coste)
+- Lee `.sdd/estado.json` antes de reescribir para detectar el scope de la spec activa
+- Los 7 patrones de referencia están documentados en `docs-site/` bajo la sección Prompts

package/presets/enterprise.yaml

@@ -50,6 +50,12 @@ agentes:
   investigador:
     activo: true
     modelo: sonnet
+  product-designer:
+    activo: true
+    modelo: opus          # diseño de producto riguroso
+  architecture-designer:
+    activo: true
+    modelo: opus          # arquitectura crítica → opus siempre
 
 comportamiento:
   deteccion_tamano_automatica: true

package/presets/lean.yaml

@@ -46,6 +46,10 @@ agentes:
     activo: false
   investigador:
     activo: false         # no hay equipo que necesite el contexto documentado
+  product-designer:
+    activo: false         # sin diseño formal de producto
+  architecture-designer:
+    activo: false         # tú diseñas la arquitectura
 
 comportamiento:
   deteccion_tamano_automatica: true

package/presets/startup.yaml

@@ -50,6 +50,12 @@ agentes:
   investigador:
     activo: true
     modelo: sonnet
+  product-designer:
+    activo: true
+    modelo: sonnet
+  architecture-designer:
+    activo: true
+    modelo: opus          # decisiones de arquitectura → opus
 
 comportamiento:
   deteccion_tamano_automatica: true

package/skills/adr-indexer/SKILL.md

@@ -0,0 +1,181 @@
+---
+name: adr-indexer
+model: claude-haiku-4-5
+description: Indexa decisiones arquitectónicas (ADR) desde comentarios en código
+allowed-tools: Read, Write, Bash
+---
+
+# Skill: ADR Indexer
+
+**Propósito:** Capturar automáticamente decisiones arquitectónicas de comentarios en código y mantener un índice buscable.
+
+---
+
+## Cómo Funciona
+
+### Patrón ADR en Comentarios
+
+El desarrollador (agente) deja una nota en el código:
+
+```python
+# ADR: {"decision": "Use PostgreSQL", "context": "ACID needed", "status": "accepted"}
+class Database:
+    pass
+```
+
+### Hook Captura Automáticamente
+
+Hook `agent-memory.js` detecta comentarios con patrón `ADR: {...}` y:
+1. Extrae JSON
+2. Valida estructura
+3. Guarda en `.sdd/arquitectura/ADRs.jsonl`
+
+### Usuario Consulta
+
+```bash
+/sdd.adr list
+→ Tabla de decisiones
+
+/sdd.adr search "database"
+→ Solo ADRs que mencionan "database"
+
+/sdd.adr new
+→ Captura interactiva de nueva decisión
+```
+
+---
+
+## Estructura de ADR
+
+```json
+{
+  "ts": "2026-06-14T10:30:00Z",
+  "decision": "Use PostgreSQL for relational data",
+  "context": "ACID transactions required, multi-tenant",
+  "alternatives": ["MongoDB", "Firebase"],
+  "status": "accepted",
+  "archivo": "src/database.ts",
+  "linea": 42
+}
+```
+
+**Campos:**
+- `ts` — timestamp (automático)
+- `decision` — qué se decidió
+- `context` — por qué
+- `alternatives` — opciones consideradas
+- `status` — accepted | rejected | deprecated | superseded
+- `archivo` — dónde está el código
+- `linea` — número de línea
+
+---
+
+## Ledger: `.sdd/arquitectura/ADRs.jsonl`
+
+Append-only JSONL:
+```
+{"ts":"2026-06-14T10:30:00Z","decision":"Use PostgreSQL","status":"accepted",...}
+{"ts":"2026-06-14T10:31:00Z","decision":"Use Redis for cache","status":"accepted",...}
+{"ts":"2026-06-14T10:32:00Z","decision":"JWT for auth","status":"accepted",...}
+```
+
+**Ventajas:**
+- Histórico completo
+- Búsqueda rápida (grep)
+- Estadísticas fáciles (contar, agrupar por status)
+- Reversible (append-only, nunca sobrescrito)
+
+---
+
+## Uso Interactivo
+
+### `/sdd.adr list`
+
+```
+ID | DECISION                  | CONTEXT              | STATUS
+───┼───────────────────────────┼──────────────────────┼──────────
+1  | Use PostgreSQL            | ACID needed          | accepted
+2  | Cache with Redis          | Performance req      | accepted
+3  | JWT instead of sessions   | Stateless API        | accepted
+```
+
+### `/sdd.adr search "security"`
+
+```
+ID | DECISION                | STATUS
+───┼───────────────────────────┼──────────
+1  | HTTPS only              | accepted
+2  | Validate all user input | accepted
+3  | Encrypt passwords       | accepted
+```
+
+### `/sdd.adr new`
+
+```
+Nuevo ADR — responde las preguntas:
+1. Decisión: "Use DynamoDB para analytics"
+2. Contexto: "Scale infinitamente, baja latencia"
+3. Alternativas: "PostgreSQL partitioning, BigQuery"
+4. Status: "accepted" (o "rejected", "deprecated")
+
+✅ Guardado en ADRs.jsonl
+```
+
+---
+
+## Implementación Técnica
+
+### En Hook: `agent-memory.js`
+
+```javascript
+function extraerADRsDelContenido(contenido) {
+  // Regex multilenguaje: //, /*, #, --, etc.
+  const regex = /(?:\/\/|\/\*|#|--|<!--|REM)\s*ADR:\s*({[^}]*})/g;
+  const adrs = [];
+  let match;
+  while ((match = regex.exec(contenido)) !== null) {
+    try {
+      const json = JSON.parse(match[1]);
+      adrs.push(json);
+    } catch {
+      // Ignorar JSON inválido
+    }
+  }
+  return adrs;
+}
+
+function registrarADR(cwd, agente, archivo, adrs) {
+  const ledgerFile = join(cwd, ".sdd/arquitectura/ADRs.jsonl");
+  for (const adr of adrs) {
+    const linea = JSON.stringify({
+      ts: new Date().toISOString(),
+      ...adr,
+      archivo: archivo,
+      agente: agente
+    });
+    appendFileSync(ledgerFile, linea + "\n", "utf8");
+  }
+}
+```
+
+---
+
+## CLI: `adr-parser.js`
+
+Batch scan del codebase:
+
+```bash
+node utils/adr-parser.js . src/**/*.ts --update-ledger
+```
+
+Encuentra todos los ADRs en archivos existentes y los añade al ledger.
+
+---
+
+## Notas
+
+- **Multilenguaje:** Soporta comentarios en Python, JS, Go, Java, Rust, etc.
+- **Idempotente:** Escanear 2 veces = mismos resultados (sin duplicados)
+- **Seguro:** JSON validado antes de guardar, error silencioso si es inválido
+- **Performante:** Regex simple, <100ms para archivo de 100KB
+

package/skills/cache-audit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 description: Audita los archivos de agentes (.claude/agents/*.md) para detectar bloques estables susceptibles de cache_control y los 3 patrones que invalidan caché silenciosamente (timestamps dinámicos, UUIDs, contenido JSONL embebido). Produce una lista de oportunidades de caché ordenadas por impacto.
-model: claude-haiku-4-5-20251001
+model: haiku
 allowed-tools: Read, Bash
 ---
 

package/skills/critica-diseno/SKILL.md

@@ -1,6 +1,6 @@
 ---
 description: Auto-crítica del wireframe generado. Evalúa en 5 dimensiones con score 1-5. Si score < 4 y iteraciones < 3, refina el artefacto y repite. Adaptado de critique-theater de open-design.
-model: claude-sonnet-4-6
+model: sonnet
 allowed-tools: Read, Write
 ---
 

package/skills/descubrir-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 description: Discovery form de 5 preguntas para entender la idea del usuario antes de interpretar. Genera contexto estructurado que alimenta el Interpreter.
-model: claude-opus-4-8
+model: opus
 allowed-tools: Write
 ---
 

package/skills/effort-router/SKILL.md

@@ -1,6 +1,6 @@
 ---
 description: Dado el nombre de la fase SDD actual, recomienda effort (low/medium/high/max) y modelo (Haiku/Sonnet/Opus) para cada agente. Evita pagar Opus cuando Sonnet o Haiku son suficientes — ahorro típico del 60-75% en fases mecánicas.
-model: claude-haiku-4-5-20251001
+model: haiku
 allowed-tools: Read
 ---
 

package/skills/elegir-direccion/SKILL.md

@@ -1,6 +1,6 @@
 ---
 description: Direction picker inspirado en open-design. Selecciona 3 de las 5 direcciones visuales disponibles según el tipo de producto y audiencia del IR, y el usuario elige una antes de generar cualquier diseño.
-model: claude-sonnet-4-6
+model: sonnet
 allowed-tools: Read, Write
 ---
 

package/skills/interpretar-idea/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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
+model: opus
 allowed-tools: Read, Write
 ---
 

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.