don-cheli-sdd 1.13.0

package/comandos/especdev/traspasar.md

@@ -0,0 +1,76 @@
+---
+description: Generar documento de traspaso estructurado para retomar en la próxima sesión
+i18n: true
+---
+
+# /especdev:traspasar
+
+## Objetivo
+
+Generar un documento de traspaso estructurado que permite a la **siguiente sesión** (o agente) retomar exactamente donde se dejó. Diferente de `/especdev:cerrar-sesion` que es un checklist para ti — el traspaso es un documento escrito para **el siguiente lector**.
+
+> Adaptado de `session-handoff` de Pro-Workflow.
+
+## Uso
+
+```
+/especdev:traspasar
+```
+
+## Output
+
+```markdown
+# Traspaso de Sesión — 2026-03-21 16:45
+
+## Estado
+- **Branch:** feature/oauth-login
+- **Commits esta sesión:** 3
+- **Cambios sin commit:** 2 archivos
+- **Tests:** ✅ pasando
+
+## ✅ Completado
+- Endpoint POST /api/auth/google
+- Endpoint POST /api/auth/github
+- 12 unit tests para ambos endpoints
+- Middleware de validación de tokens OAuth
+
+## 🔄 En Progreso
+- Refresh token (src/services/auth/refresh.ts:23)
+  → Falta implementar rotación de tokens
+  → El test skeleton ya existe en tests/auth/refresh.test.ts
+
+## ⬜ Pendiente
+- [ ] Vincular OAuth a cuenta existente por email
+- [ ] Revocar token al logout
+- [ ] BLOQUEADO: Endpoint de callback necesita URL de producción
+
+## 🧠 Decisiones Tomadas
+- Elegido Strategy Pattern para providers (Google, GitHub)
+  → Razón: extensible para Apple/Microsoft después
+- Tokens JWT con 15min de vida + refresh de 7 días
+  → Razón: balance seguridad/UX
+
+## 📄 Archivos Tocados
+- `src/services/auth/google.ts` — Provider de Google OAuth
+- `src/services/auth/github.ts` — Provider de GitHub OAuth
+- `src/middleware/oauth-validate.ts` — Validación de tokens
+- `tests/auth/google.test.ts` — 6 tests
+- `tests/auth/github.test.ts` — 6 tests
+
+## ⚠️ Gotchas
+- NextAuth v5 cambia la API: `getSession()` ahora es async
+- El mock de Google no devuelve `refresh_token` en primer login
+
+## ▶️ Comando de Retomar
+
+> Continuar en branch `feature/oauth-login`. Implementar refresh token
+> (src/services/auth/refresh.ts). El test skeleton ya está. Siguiente
+> paso: implementar rotación de tokens en el endpoint POST /api/auth/refresh.
+```
+
+## Guardrails
+
+- **Escribir para el lector** — No para ti
+- **Incluir paths y líneas** — Ser específico
+- **Comando de retomar copy-pasteable** — 1-2 oraciones de contexto
+- **Solo hechos** — Describir cambios funcionalmente, no inferir motivación

package/comandos/especdev/traspaso.md

@@ -0,0 +1,43 @@
+---
+description: Generar handoff de contexto para transferencia de sesión
+i18n: true
+---
+
+# /especdev:traspaso
+
+## Objetivo
+
+Generar un documento estructurado para transferir contexto entre sesiones o agentes.
+
+## Uso
+
+```
+/especdev:traspaso
+/especdev:traspaso --guardar
+/especdev:traspaso --formato md
+/especdev:traspaso --destino agente
+```
+
+## Output
+
+```xml
+<traspaso_contexto>
+  <metadatos>
+    <proyecto>api-pagos</proyecto>
+    <fecha>2026-03-21T15:30:00Z</fecha>
+  </metadatos>
+  <tarea_original>Implementar API de pagos</tarea_original>
+  <trabajo_completado>
+    - Spec Gherkin creada
+    - Blueprint técnico generado
+  </trabajo_completado>
+  <trabajo_pendiente>
+    - Implementar endpoint de cobro
+    - Agregar tests de integración
+  </trabajo_pendiente>
+  <estado_actual>
+    Fase: 4/7
+    Progreso: 55%
+  </estado_actual>
+</traspaso_contexto>
+```

package/comandos/especdev/uat.md

@@ -0,0 +1,84 @@
+---
+description: Generar scripts de User Acceptance Testing para validación humana
+i18n: true
+---
+
+# /especdev:uat
+
+## Objetivo
+
+Generar automáticamente un script de pruebas de aceptación (UAT) ejecutable por un humano después de completar un slice o feature. El script describe paso a paso qué verificar, qué resultado esperar, y cómo reportar fallos.
+
+## Uso
+
+```
+/especdev:uat                           # Genera UAT para el slice actual
+/especdev:uat @specs/features/auth/     # Genera UAT para un dominio específico
+/especdev:uat --formato checklist       # Solo checklist sin narrativa
+```
+
+## Comportamiento
+
+1. **Leer** las specs Gherkin del slice/feature
+2. **Extraer** los escenarios P1 y P2
+3. **Generar** pasos de prueba ejecutables por un humano
+4. **Incluir** datos de prueba concretos (no genéricos)
+5. **Guardar** en `.especdev/uat/<feature>.uat.md`
+
+## Output
+
+```markdown
+# UAT: Notificaciones Push
+
+**Feature:** notificaciones/NotificacionesPush
+**Generado:** 2026-03-22
+**Tiempo estimado:** 15 minutos
+
+## Pre-requisitos
+- [ ] App instalada en dispositivo físico (no simulador)
+- [ ] Permisos de notificación otorgados
+- [ ] Liga "La Liga" marcada como favorita
+- [ ] Al menos un partido de La Liga en vivo o programado hoy
+
+## Pruebas
+
+### UAT-001: Recibir notificación de gol ⭐ P1
+**Pasos:**
+1. Abrir la app y verificar que muestra partidos en vivo
+2. Minimizar la app (dejar en background)
+3. Esperar a que ocurra un gol en un partido de La Liga
+   - *Alternativa: usar endpoint de test `POST /api/test/simulate-goal`*
+
+**Resultado esperado:**
+- [ ] Notificación push recibida en < 10 segundos
+- [ ] Título contiene "⚽ ¡GOL!" + marcador actualizado
+- [ ] Cuerpo contiene nombre del goleador y minuto
+- [ ] Al tocar la notificación, abre el detalle del partido
+
+**Si falla:** Reportar captura de pantalla + modelo de dispositivo + versión OS
+
+### UAT-002: Sin permisos no llegan notificaciones ⭐ P1
+**Pasos:**
+1. Revocar permisos de notificación en Ajustes del dispositivo
+2. Abrir la app
+3. Esperar evento de gol
+
+**Resultado esperado:**
+- [ ] NO llega notificación push
+- [ ] Al abrir la app, el evento es visible en el timeline del partido
+
+## Resumen
+| ID | Descripción | Resultado | Notas |
+|----|-------------|-----------|-------|
+| UAT-001 | Notificación de gol | ⬜ | |
+| UAT-002 | Sin permisos | ⬜ | |
+
+**Firma del tester:** _______________
+**Fecha:** _______________
+```
+
+## Integración
+
+- Se genera automáticamente al completar `/especdev:implementar` para cada feature
+- Se incluye en la descripción del PR como evidencia de testing manual
+- Se archiva con `/especdev:archivar`

package/comandos/especdev/validar-spec.md

@@ -0,0 +1,58 @@
+---
+description: Validar la calidad y completitud de una especificación antes de planificar
+i18n: true
+---
+
+# /especdev:validar-spec
+
+## Objetivo
+
+Ejecutar una validación multi-capa sobre las especificaciones ANTES de desglosar en tareas. Detecta problemas que `/especdev:clarificar` no cubre: implementation leakage, measurability, completeness, y adherencia a la constitución del proyecto.
+
+Inspirado en los 13 pasos de validación del framework BMAD.
+
+## Uso
+
+```
+/especdev:validar-spec                              # Validar todas las specs activas
+/especdev:validar-spec @specs/features/auth/         # Validar un dominio
+/especdev:validar-spec --strict                      # Modo estricto (0 warnings permitidos)
+```
+
+## Validaciones (8 checks)
+
+| # | Check | Qué detecta | Severidad |
+|---|-------|-------------|-----------|
+| 1 | **Implementation Leakage** | ¿La spec menciona tecnologías donde no debería? (WHAT vs HOW) | 🔴 Error |
+| 2 | **Measurability** | ¿Los criterios de aceptación son medibles y verificables? | 🟠 Warning |
+| 3 | **Completeness** | ¿Hay happy path + sad paths + edge cases para cada scenario? | 🔴 Error |
+| 4 | **Traceability** | ¿Cada requisito tiene al menos un escenario que lo cubre? | 🔴 Error |
+| 5 | **Constitution Adherence** | ¿La spec respeta los principios de constitucion-proyecto.md? | 🔴 Error |
+| 6 | **Consistency** | ¿Hay contradicciones entre escenarios o entre features? | 🟠 Warning |
+| 7 | **Ambiguity** | ¿Hay términos ambiguos o no definidos? (complementa clarificar) | 🟠 Warning |
+| 8 | **Scope Alignment** | ¿La spec está dentro del alcance definido en la propuesta? | 🟠 Warning |
+
+## Output
+
+```
+📋 Validación de Spec: demo-sdd
+
+✅ PASS: Implementation Leakage (0 violaciones)
+✅ PASS: Completeness (todos los escenarios tienen happy + sad path)
+⚠️  WARN: Measurability — 2 criterios sin umbral cuantificable
+  - VerPartidosEnVivo.feature:45 — "respuesta rápida" → ¿cuántos ms?
+  - PrediccionesIA.feature:32 — "precisión aceptable" → ¿qué porcentaje?
+✅ PASS: Traceability (100% de requisitos cubiertos)
+✅ PASS: Constitution Adherence
+✅ PASS: Consistency
+⚠️  WARN: Ambiguity — 1 término sin definir
+  - "usuario premium" usado en 3 features pero no definido en ninguna
+✅ PASS: Scope Alignment
+
+Resultado: ⚠️ PASA CON WARNINGS (2 warnings, 0 errores)
+→ Corregir warnings antes de /especdev:desglosar para máxima calidad
+```
+
+## Integración
+
+Se ejecuta automáticamente como sub-puerta de la **Puerta 3 (Clarificación)** cuando se usa el pipeline completo. También se puede ejecutar manualmente en cualquier momento.

package/comandos/especdev/validar.md

@@ -0,0 +1,40 @@
+---
+description: Validar la conformidad de archivos .especdev/
+i18n: true
+---
+
+# /especdev:validar
+
+## Objetivo
+
+Verificar que los archivos de `.especdev/` están completos y conformes.
+
+## Uso
+
+```
+/especdev:validar
+```
+
+## Verificaciones
+
+| Archivo | Verificación |
+|---------|-------------|
+| `config.yaml` | Campos requeridos presentes |
+| `estado.md` | Fase válida (1-7), progreso 0-100% |
+| `plan.md` | Al menos una fase definida |
+| `hallazgos.md` | Formato correcto |
+| `progreso.md` | Formato correcto |
+
+## Output
+
+```
+=== Validación Don Cheli ===
+
+✅ config.yaml — OK
+✅ estado.md — OK (Fase 3, 40%)
+⚠️ plan.md — Fases 5-7 sin definir
+✅ hallazgos.md — OK (3 entradas)
+✅ progreso.md — OK (4 sesiones)
+
+Resultado: 4/5 ✅, 1 advertencia
+```

package/comandos/historias-generar.md

@@ -0,0 +1,74 @@
+---
+description: Generar prd.json desde un PRD markdown para el bucle autónomo
+---
+
+# /historias-generar
+
+## Objetivo
+
+Convertir un PRD markdown en archivo `prd.json` estructurado para el bucle autónomo.
+
+## Uso
+
+```
+/historias-generar [archivo-prd.md]
+```
+
+Si no se especifica archivo, busca en orden:
+1. `.especdev/prd.md`
+2. `docs/prd.md`
+3. `PRD.md`
+
+## Formato PRD Markdown Esperado
+
+```markdown
+# Nombre del Proyecto
+
+Descripción del proyecto o feature.
+
+## Historias
+
+### HU-001: Título de la historia
+
+Como [rol], quiero [acción], para [beneficio].
+
+**Criterios de aceptación:**
+- [ ] Criterio 1
+- [ ] Criterio 2
+
+**Prioridad:** 1
+```
+
+## Formato prd.json Generado
+
+```json
+{
+  "proyecto": "Nombre del Proyecto",
+  "ramaBase": "[rama-actual]",
+  "descripcion": "Descripción...",
+  "historiasUsuario": [
+    {
+      "id": "HU-001",
+      "titulo": "Título de la historia",
+      "descripcion": "Como...",
+      "criteriosAceptacion": ["Criterio 1", "Criterio 2"],
+      "prioridad": 1,
+      "pasa": false,
+      "notas": ""
+    }
+  ]
+}
+```
+
+## Output
+
+```
+Historias generadas: 5
+Archivo: .especdev/sesion/prd.json
+
+HU-001 [P1] Título historia 1
+HU-002 [P2] Título historia 2
+...
+
+Ejecuta /bucle para implementar las historias.
+```

package/comandos/razonar/5-porques.md

@@ -0,0 +1,42 @@
+---
+description: Análisis de causa raíz preguntando "¿por qué?" repetidamente hasta llegar al origen del problema.
+i18n: true
+---
+
+# /razonar:5-porques
+
+Análisis de causa raíz preguntando "¿por qué?" repetidamente hasta llegar al origen del problema.
+
+## Uso
+
+```
+/razonar:5-porques [problema]
+```
+
+## Proceso
+
+1. Plantear el problema
+2. Preguntar "¿Por qué?" → Respuesta 1
+3. Preguntar "¿Por qué?" sobre la respuesta → Respuesta 2
+4. Repetir hasta llegar a la causa raíz (usualmente 5 niveles)
+5. Proponer solución a la causa raíz
+
+## Ejemplo
+
+```
+/razonar:5-porques "Los tests fallan intermitentemente"
+
+¿Por qué? → Condición de carrera
+¿Por qué? → Estado compartido entre tests
+¿Por qué? → Singleton global
+¿Por qué? → Diseño legacy sin revisión
+¿Por qué? → No hay proceso de revisión arquitectónica
+
+→ Causa raíz: problema de PROCESO, no solo de código
+→ Solución: Implementar revisión arquitectónica + refactorizar singleton
+```
+
+## Combina bien con
+
+- `/razonar:primeros-principios`
+- `/razonar:pre-mortem`

package/comandos/razonar/circulo-competencia.md

@@ -0,0 +1,22 @@
+---
+description: Conocer tus límites. Distinguir entre lo que conoces profundamente y lo que solo conoces superficialmente.
+i18n: true
+---
+
+# /razonar:circulo-competencia
+
+Conocer tus límites. Distinguir entre lo que conoces profundamente y lo que solo conoces superficialmente.
+
+## Uso
+
+```
+/razonar:circulo-competencia [área/decisión]
+```
+
+## Proceso
+
+1. **Definir** el área de decisión
+2. **Evaluar** honestamente: ¿es mi área de competencia?
+3. **Si SÍ**: Decidir con confianza
+4. **Si NO**: Buscar experto o investigar antes de decidir
+5. **Documentar** los límites para futuras decisiones

package/comandos/razonar/costo-oportunidad.md

@@ -0,0 +1,21 @@
+---
+description: Evaluar el costo de NO elegir las alternativas. Cada decisión tiene un costo oculto.
+i18n: true
+---
+
+# /razonar:costo-oportunidad
+
+Evaluar el costo de NO elegir las alternativas. Cada decisión tiene un costo oculto.
+
+## Uso
+
+```
+/razonar:costo-oportunidad [opciones]
+```
+
+## Proceso
+
+1. Listar todas las opciones disponibles
+2. Para cada opción: ¿qué GANO y qué PIERDO?
+3. Evaluar el costo de la mejor alternativa NO elegida
+4. Decidir si el beneficio supera el costo de oportunidad

package/comandos/razonar/inversion.md

@@ -0,0 +1,40 @@
+---
+description: Resolver un problema pensando al revés: ¿cómo GARANTIZARÍAMOS el fracaso?
+i18n: true
+---
+
+# /razonar:inversion
+
+Resolver un problema pensando al revés: ¿cómo GARANTIZARÍAMOS el fracaso?
+
+## Uso
+
+```
+/razonar:inversion [objetivo]
+```
+
+## Proceso
+
+1. **Definir** el objetivo deseado
+2. **Invertir**: ¿Cómo garantizaríamos el fracaso?
+3. **Listar** todas las formas de fallar
+4. **Invertir** cada fallo → acción preventiva
+5. **Priorizar** acciones preventivas
+
+## Ejemplo
+
+```
+/razonar:inversion "Lanzamiento exitoso de v2.0"
+
+¿Cómo GARANTIZAR que el lanzamiento falle?
+- No hacer tests de regresión
+- Desplegar un viernes a las 6pm
+- No tener plan de rollback
+- Ignorar feedback de beta testers
+
+→ Inversión = nuestro plan:
+- Tests de regresión obligatorios
+- Desplegar martes a las 10am
+- Plan de rollback documentado
+- Ciclo de beta testing
+```

package/comandos/razonar/mapa-territorio.md

@@ -0,0 +1,22 @@
+---
+description: Distinguir entre el modelo (mapa) y la realidad (territorio). El mapa NO es el territorio.
+i18n: true
+---
+
+# /razonar:mapa-territorio
+
+Distinguir entre el modelo (mapa) y la realidad (territorio). El mapa NO es el territorio.
+
+## Uso
+
+```
+/razonar:mapa-territorio [situación]
+```
+
+## Proceso
+
+1. **Identificar** el modelo/mapa que estás usando
+2. **Preguntar**: ¿Dónde podría diferir de la realidad?
+3. **Buscar** evidencia directa del territorio (datos reales)
+4. **Ajustar** el mapa donde sea necesario
+5. **Recordar**: todo modelo es una simplificación

package/comandos/razonar/minimizar-arrepentimiento.md

@@ -0,0 +1,20 @@
+---
+description: Tomar decisiones pensando en lo que minimizará el arrepentimiento a largo plazo.
+i18n: true
+---
+
+# /razonar:minimizar-arrepentimiento
+
+Tomar decisiones pensando en lo que minimizará el arrepentimiento a largo plazo.
+
+## Uso
+
+```
+/razonar:minimizar-arrepentimiento [decisión]
+```
+
+## Proceso
+
+1. Imagínate a los 80 años mirando hacia atrás
+2. ¿De cuál opción te arrepentirías más de NO haber tomado?
+3. Elegir la opción que minimiza el arrepentimiento futuro

package/comandos/razonar/pareto.md

@@ -0,0 +1,32 @@
+---
+description: Aplicar el principio 80/20: enfocarse en el 20% que produce el 80% de los resultados.
+i18n: true
+---
+
+# /razonar:pareto
+
+Aplicar el principio 80/20: enfocarse en el 20% que produce el 80% de los resultados.
+
+## Uso
+
+```
+/razonar:pareto [contexto]
+```
+
+## Proceso
+
+1. **Listar** todos los elementos (features, bugs, tareas)
+2. **Evaluar** el impacto de cada uno
+3. **Ordenar** por impacto descendente
+4. **Identificar** el 20% de mayor impacto
+5. **Enfocar** recursos en ese 20%
+
+## Ejemplo
+
+```
+/razonar:pareto "20 features solicitadas"
+
+→ ¿Cuáles 20% entregarán 80% del valor?
+→ Enfocarse en 4 features de alto impacto
+→ Las 16 restantes pueden esperar
+```

package/comandos/razonar/pre-mortem.md

@@ -0,0 +1,22 @@
+---
+description: Anticipar el fracaso ANTES de que ocurra. Imaginar que el proyecto ya falló y analizar por qué.
+i18n: true
+---
+
+# /razonar:pre-mortem
+
+Anticipar el fracaso ANTES de que ocurra. Imaginar que el proyecto ya falló y analizar por qué.
+
+## Uso
+
+```
+/razonar:pre-mortem [proyecto/decisión]
+```
+
+## Proceso
+
+1. **Imaginar** que el proyecto ya falló completamente
+2. **Preguntar**: "¿Por qué falló?"
+3. **Listar** todas las causas posibles
+4. **Evaluar** probabilidad e impacto de cada una
+5. **Crear** plan de mitigación para las más probables

package/comandos/razonar/primeros-principios.md

@@ -0,0 +1,57 @@
+---
+description: Descomponer un problema o suposición a sus verdades fundamentales, luego reconstruir el entendimiento desde cero.
+i18n: true
+---
+
+# /razonar:primeros-principios
+
+Descomponer un problema o suposición a sus verdades fundamentales, luego reconstruir el entendimiento desde cero.
+
+## Uso
+
+```
+/razonar:primeros-principios [tema]
+```
+
+## Descripción
+
+El Pensamiento de Primeros Principios te ayuda a escapar de la sabiduría convencional cuestionando suposiciones. En vez de razonar por analogía ("¿cómo lo hacen otros?"), razonas desde lo básico ("¿qué es fundamentalmente verdad?").
+
+**Usar cuando:**
+- Los enfoques convencionales se sienten incorrectos
+- Necesitas innovación, no iteración
+- Las suposiciones están limitando las opciones
+- Enfrentas restricciones "imposibles"
+
+## Proceso
+
+1. **Identificar suposiciones** — Listar lo que das por sentado
+2. **Descomponer a lo fundamental** — ¿Qué es innegablemente verdad?
+3. **Cuestionar cada suposición** — ¿Es realmente necesaria?
+4. **Reconstruir desde lo básico** — ¿Qué soluciones emergen de lo fundamental?
+
+## Ejemplo
+
+```
+/razonar:primeros-principios "Necesitamos microservicios para escalar"
+
+SUPOSICIONES:
+- Los microservicios son necesarios para escalar
+- Los monolitos no escalan
+- Las empresas grandes saben más
+
+FUNDAMENTOS:
+- Necesitamos X solicitudes/segundo
+- Tenemos Y desarrolladores
+- Necesitamos Z frecuencia de despliegue
+
+RECONSTRUCCIÓN:
+Nuestra escala: 1000 req/s → El monolito maneja fácilmente
+Nuestro equipo: 5 devs → Pueden coordinarse en monolito
+Conclusión: Un monolito modular nos sirve mejor
+```
+
+## Combina bien con
+
+- `/razonar:inversion`
+- `/razonar:5-porques`

package/comandos/razonar/probabilistico.md

@@ -0,0 +1,21 @@
+---
+description: Razonar en probabilidades en vez de certezas. Asignar porcentajes a los posibles resultados.
+i18n: true
+---
+
+# /razonar:probabilistico
+
+Razonar en probabilidades en vez de certezas. Asignar porcentajes a los posibles resultados.
+
+## Uso
+
+```
+/razonar:probabilistico [escenario]
+```
+
+## Proceso
+
+1. **Listar** todos los posibles resultados
+2. **Asignar** probabilidad a cada uno (deben sumar 100%)
+3. **Evaluar** el valor esperado de cada opción
+4. **Decidir** basándose en el valor esperado, no en el mejor caso