don-cheli-sdd 1.13.0

package/scripts/.claude/commands/especdev/revisar.md

@@ -0,0 +1,221 @@
+---
+description: Peer review estricto con análisis de rendimiento, arquitectura, seguridad y cumplimiento
+i18n: true
+---
+
+# /especdev:revisar
+
+## Objetivo
+
+Generar un peer review estricto asumiendo el rol de **Arquitecto de Software / Lead Developer**. Evalúa no solo sintaxis y tests, sino rendimiento, cumplimiento de arquitectura, seguridad y eficiencia algorítmica.
+
+## Uso
+
+```
+/especdev:revisar
+/especdev:revisar @specs/features/<dominio>/<Feature>.tasks.md
+/especdev:revisar --rigor alto                   # Review de arquitecto senior
+/especdev:revisar --rigor estandar               # Review estándar (default)
+/especdev:revisar --foco rendimiento             # Enfocarse en performance
+/especdev:revisar --foco seguridad               # Enfocarse en seguridad
+```
+
+## Dimensiones del Review
+
+### 1. Corrección Funcional
+
+```
+Verificar:
+  - [ ] Todos los escenarios Gherkin P1 implementados
+  - [ ] Escenarios P2 implementados
+  - [ ] Edge cases cubiertos con tests
+  - [ ] Sin stubs detectados (habilidad detección-stubs)
+  - [ ] Criterios de éxito de la spec cumplidos
+```
+
+### 2. Tests y Cobertura
+
+```
+Verificar:
+  - [ ] Tests unitarios pasan
+  - [ ] Tests de integración pasan
+  - [ ] Tests BDD desde Gherkin pasan
+  - [ ] Cobertura ≥ 85% sobre código nuevo
+  - [ ] Validación Nyquist: 100% P1, 80% P2
+  - [ ] Tests verifican comportamiento, no implementación
+  - [ ] Sin tests frágiles (no dependen de orden, tiempo, estado global)
+```
+
+### 3. Rendimiento
+
+```
+Detectar:
+  ❌ Consultas N+1 a base de datos
+  ❌ Loops innecesarios sobre datasets grandes (O(n²) evitable)
+  ❌ Falta de paginación en queries que pueden crecer
+  ❌ Objetos grandes en memoria sin liberar
+  ❌ Imports pesados que podrían ser lazy
+  ❌ Re-renders innecesarios (React) o watchers excesivos (Vue)
+  ❌ Falta de índices en queries frecuentes
+  ❌ Serialización/deserialización redundante
+```
+
+### 4. Arquitectura y Diseño
+
+```
+Verificar:
+  - [ ] Cumple con constitución (todos los artículos)
+  - [ ] Principios SOLID respetados (habilidad refactorizacion-solid)
+  - [ ] Contrato UI respetado (si aplica, habilidad contrato-ui)
+  - [ ] Sin acoplamiento excesivo entre módulos
+  - [ ] Dependencias inyectadas (no hardcoded)
+  - [ ] Separación de concerns (controller thin, service con lógica)
+  - [ ] Sin código duplicado significativo (>10 líneas)
+```
+
+### 5. Seguridad
+
+```
+Verificar (subset de auditar-seguridad):
+  - [ ] Input validado en puntos de entrada
+  - [ ] Queries parametrizadas (no concatenación)
+  - [ ] Sin credenciales en código
+  - [ ] Auth/authz en endpoints que lo requieren
+  - [ ] Output encodado (prevención XSS)
+  - [ ] Sin datos sensibles en logs
+```
+
+### 6. Estilo y Convenciones
+
+```
+Verificar:
+  - [ ] Naming consistente con convenciones del proyecto
+  - [ ] Sin imports no usados
+  - [ ] Sin variables no usadas
+  - [ ] Sin console.log/print de debugging
+  - [ ] Lint y type-check sin errores
+  - [ ] Comentarios que aportan valor (no ruido)
+```
+
+### 7. Diff Limpio
+
+```
+Verificar:
+  - [ ] Solo cambios relacionados a la feature
+  - [ ] Sin refactoring "de paso" (Art. II Constitución)
+  - [ ] Sin cambios de formato no relacionados
+  - [ ] Sin archivos de configuración personal (.vscode, .idea)
+  - [ ] Sin archivos binarios innecesarios
+```
+
+## Output
+
+Genera `specs/features/<dominio>/revision.md`:
+
+```markdown
+# Peer Review: CrearUsuario
+
+**Revisor:** Don Cheli Peer Review v2.0
+**Fecha:** 2026-03-21
+**Rigor:** Alto (Arquitecto Senior)
+**Archivos revisados:** 8
+
+---
+
+## Veredicto: ⚠️ APROBADO CON OBSERVACIONES
+
+---
+
+## 1. Corrección Funcional ✅
+- P1: 3/3 escenarios implementados
+- P2: 2/2 escenarios implementados
+- Stubs: 0 detectados
+
+## 2. Tests y Cobertura ✅
+- Unitarios: 12/12 ✅
+- Integración: 4/4 ✅
+- BDD: 5/5 ✅
+- Cobertura: 89% (≥ 85% ✅)
+- Nyquist P1: 100% ✅
+
+## 3. Rendimiento ⚠️
+
+### ⚠️ PERF-001: Consulta N+1 potencial
+**Archivo:** src/services/usuario_service.py:67
+**Descripción:** Al listar usuarios con sus roles, se ejecuta 1 query por rol.
+```python
+# Actual (N+1)
+for user in users:
+    user.roles = await role_repo.find_by_user(user.id)
+
+# Sugerido (1 query)
+user_ids = [u.id for u in users]
+roles_map = await role_repo.find_by_users(user_ids)
+for user in users:
+    user.roles = roles_map.get(user.id, [])
+```
+**Impacto:** Bajo ahora (pocos usuarios), pero escala linealmente.
+**Acción:** Corregir antes de que la tabla usuarios crezca.
+
+## 4. Arquitectura y Diseño ✅
+- Constitución: todos los artículos ✅
+- SOLID: sin violaciones detectadas
+- Separación de concerns: controller thin ✅
+- DI: todas las dependencias inyectadas ✅
+
+## 5. Seguridad ✅
+- Input validado con Pydantic ✅
+- Queries parametrizadas (SQLAlchemy) ✅
+- Password con argon2id ✅
+- Sin credenciales en código ✅
+
+## 6. Estilo y Convenciones ✅
+- Naming consistente ✅
+- Lint: 0 errores ✅
+- Type-check: 0 errores ✅
+- Sin console.log ✅
+
+## 7. Diff Limpio ✅
+- Solo archivos de la feature ✅
+- Sin cambios de formato ✅
+
+---
+
+## Resumen de Hallazgos
+
+| ID | Tipo | Severidad | Estado |
+|----|------|-----------|--------|
+| PERF-001 | Rendimiento | ⚠️ Medio | Pendiente |
+
+## Recomendaciones
+1. Corregir N+1 en listado de usuarios (PERF-001)
+2. Considerar agregar índice en `email` si aún no existe
+3. Agregar rate limiting en POST /usuarios para v2
+```
+
+## Niveles de Rigor
+
+| Rigor | Quién simula | Dimensiones | Cuándo usar |
+|-------|-------------|-------------|-------------|
+| **Básico** | Developer Jr | 1, 2, 6 | Fix rápido, cambio menor |
+| **Estándar** | Senior Dev | 1-4, 6, 7 | Features estándar |
+| **Alto** | Arquitecto Senior | 1-7 (todas) | Features críticas, auth, pagos |
+
+## Integración con Pipeline
+
+```
+/especdev:implementar → código completo
+  → /especdev:revisar → reporte de review
+  → ¿Aprobado?
+     ├── ✅ APROBADO → listo para PR
+     ├── ⚠️ CON OBSERVACIONES → corregir hallazgos → re-revisar
+     └── ❌ RECHAZADO → cambios significativos necesarios
+```
+
+## Guardrails
+
+- **Nunca** aprobar código con stubs críticos
+- **Nunca** aprobar sin tests (Ley de Hierro #1)
+- **Nunca** ignorar hallazgos de seguridad
+- **Siempre** verificar cumplimiento de constitución
+- **Siempre** documentar hallazgos con archivo + línea + sugerencia

package/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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/scripts/.claude/commands/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