don-cheli-sdd 1.13.0

package/comandos/especdev/proponer.md

@@ -0,0 +1,69 @@
+---
+description: Crear propuesta de cambio con intención, alcance y enfoque antes de especificar
+i18n: true
+---
+
+# /especdev:proponer
+
+## Objetivo
+
+Crear una propuesta de cambio estructurada ANTES de escribir la especificación Gherkin. Define la intención (WHY), el alcance (WHAT) y el enfoque (HOW) del cambio.
+
+> Adaptado de `sdd-propose` de Gentle-AI — fase intermedia entre explorar y especificar.
+
+## Uso
+
+```
+/especdev:proponer <descripción del cambio>
+```
+
+## Por Qué Existe
+
+Sin una propuesta formal, los developers saltan directo a escribir specs sin
+alinear la intención con el stakeholder. La propuesta:
+- Fuerza a pensar en el **POR QUÉ** antes del **QUÉ**
+- Define el alcance explícito (qué SÍ, qué NO)
+- Identifica riesgos antes de invertir tiempo en specs
+
+## Output
+
+```markdown
+# Propuesta: Implementar Autenticación OAuth
+
+## Intención (POR QUÉ)
+Los usuarios piden login social. El 60% abandona el registro manual.
+
+## Alcance (QUÉ)
+### Incluido
+- Login con Google y GitHub
+- Vinculación de cuenta OAuth a cuenta existente
+- Token refresh automático
+
+### Excluido
+- Login con Facebook (baja demanda)
+- 2FA con OAuth (fase posterior)
+
+## Enfoque (CÓMO)
+- Usar passport.js para providers
+- Almacenar tokens encriptados en BD
+- Flujo: redirect → callback → JWT interno
+
+## Riesgos
+- Dependencia de APIs externas de Google/GitHub
+- Complejidad de vinculación de cuentas existentes
+
+## Estimado Preliminar
+- Complejidad: Nivel 2 (Estándar)
+- Tiempo: 3-5 días
+- Archivos afectados: ~8-12
+
+## Estado: PENDIENTE APROBACIÓN
+```
+
+## Integración
+
+```
+/especdev:explorar → hallazgos.md
+→ /especdev:proponer → propuesta.md (ESTE COMANDO)
+→ /especdev:especificar → .feature (solo después de aprobar propuesta)
+```

package/comandos/especdev/pseudocodigo.md

@@ -0,0 +1,49 @@
+---
+description: Generar pseudocódigo agnóstico de tecnología desde las specs antes de planificar
+i18n: true
+---
+
+# /especdev:pseudocodigo
+
+## Objetivo
+
+Crear un artefacto de pseudocódigo de alto nivel entre la fase de especificación y la planificación técnica. Fuerza al agente a razonar sobre la LÓGICA del sistema sin comprometer stack, framework o estructura de archivos.
+
+Inspirado en la fase "P" (Pseudocode) del framework SPARC.
+
+## Uso
+
+```
+/especdev:pseudocodigo                    # Desde las specs del sprint actual
+/especdev:pseudocodigo @specs/auth/       # Para un dominio específico
+```
+
+## Comportamiento
+
+1. **Leer** las specs Gherkin del dominio
+2. **Extraer** los flujos principales (happy path + sad paths)
+3. **Generar** pseudocódigo agnóstico:
+   - Sin nombres de funciones reales
+   - Sin imports ni frameworks
+   - Sin tipos de datos específicos del lenguaje
+   - Solo lógica: CUANDO/SI/SINO/PARA-CADA/RETORNAR
+4. **Identificar** invariantes (condiciones siempre verdaderas)
+5. **Listar** casos límite y dependencias de datos
+6. **Guardar** en `.especdev/pseudocodigo.md`
+
+## Por qué existe
+
+Sin pseudocódigo, el agente salta de "qué hacer" (spec) a "cómo implementar" (plan técnico) sin pasar por "qué lógica necesito". Esto causa:
+- Sobre-ingeniería (resolver problemas que no existen)
+- Under-ingeniería (olvidar edge cases obvios)
+- Acoplamiento temprano a un framework
+
+El pseudocódigo es el "boceto" del arquitecto antes de los planos.
+
+## Integración en el Pipeline
+
+```
+especificar → clarificar → PSEUDOCÓDIGO → planificar-tecnico → desglosar → implementar
+```
+
+Es opcional pero recomendado para tareas de complejidad ≥ 2 (Estándar).

package/comandos/especdev/rapido.md

@@ -0,0 +1,69 @@
+---
+description: Modo rápido para tareas pequeñas y bien definidas (Nivel 1)
+i18n: true
+---
+
+# /especdev:rapido
+
+## Objetivo
+
+Iniciar modo rápido (Nivel 1 - Micro) para tareas pequeñas y bien definidas.
+
+## Uso
+
+```
+/especdev:rapido <descripción de la tarea>
+```
+
+## Cuándo Usar
+
+- Tarea bien definida (inicio y fin claros)
+- Solución conocida
+- Alcance pequeño (1-3 tareas, < 1 día)
+- Sin decisiones arquitectónicas
+- Fácil de revertir
+
+## Proceso (3 fases)
+
+### Fase 1: Planear (5 min)
+
+```markdown
+## Tarea Rápida: [título]
+
+**Meta:** [una línea]
+**Enfoque:** [2-3 oraciones]
+**Tareas:**
+- [ ] Tarea 1
+- [ ] Tarea 2
+- [ ] Tarea 3
+
+**Completado cuando:** [criterio de éxito]
+```
+
+### Fase 2: Ejecutar (trabajo principal)
+
+1. Ejecutar tareas secuencialmente
+2. Aplicar Leyes de Hierro (TDD, debugging, verificación)
+3. Registrar progreso en `.especdev/progreso.md`
+
+### Fase 3: Verificar (5 min)
+
+```markdown
+## Verificación
+- [ ] Todas las tareas completadas
+- [ ] Tests pasan
+- [ ] Sin regresiones
+- [ ] Código commitado
+```
+
+## Escalamiento Automático
+
+Si se detecta complejidad → auto-escalar a `/especdev:completo`
+
+```
+¿Puedo resolver esto en < 5 min sin cambiar cómo las cosas trabajan juntas?
+├── SÍ → Continuar en modo rápido
+└── NO → ¿Necesita una decisión de diseño?
+          ├── SÍ → Escalar a modo completo
+          └── NO → Registrar y continuar
+```

package/comandos/especdev/reflexionar.md

@@ -0,0 +1,53 @@
+---
+description: Reflexionar sobre una tarea para mejorar calidad (+8-21%)
+i18n: true
+---
+
+# /especdev:reflexionar
+
+## Objetivo
+
+Aplicar reflexión estructurada sobre una tarea completada para mejorar la calidad del output. La investigación muestra **+8-21% de mejora** en calidad de tareas.
+
+## Uso
+
+```
+/especdev:reflexionar [tema]
+```
+
+## Las 4 Preguntas
+
+1. **¿Qué funcionó bien?** → Identificar patrones exitosos
+2. **¿Qué se puede mejorar?** → Encontrar brechas de calidad
+3. **¿Qué aprendí?** → Extraer insights
+4. **¿Qué haría diferente?** → Considerar alternativas
+
+## Cuándo Reflexionar
+
+| Disparador | Acción |
+|-----------|--------|
+| Tarea compleja completada | Siempre reflexionar |
+| Usuario solicita revisión | Siempre reflexionar |
+| "reflexionar" en el prompt | Auto-activado |
+| Tarea mecánica simple | Omitir (costo > beneficio) |
+
+## Ejemplo
+
+```markdown
+## Reflexión: Implementación de API
+
+### Qué Funcionó Bien ✅
+- Separación de responsabilidades limpia
+- Buena cobertura de tests (87%)
+
+### Qué Se Puede Mejorar 🔧
+- Tiempo de respuesta en búsqueda (800ms → meta 200ms)
+- Falta documentación de rate limiting
+
+### Qué Aprendí 💡
+- Índices de base de datos tienen 10x impacto en búsquedas
+- Testing de rendimiento temprano previene sorpresas tardías
+
+### Qué Haría Diferente 🔄
+- Agregar benchmarks de rendimiento desde el día 1
+```

package/comandos/especdev/retro.md

@@ -0,0 +1,14 @@
+---
+description: Ver detalles de una sesión pasada
+i18n: true
+---
+
+# /especdev:retro
+
+## Uso
+
+```
+/especdev:retro <sesion>
+```
+
+Muestra los detalles de una sesión pasada almacenada en `.especdev/historial/`.

package/comandos/especdev/reversa.md

@@ -0,0 +1,155 @@
+---
+description: Extraer arquitectura de un codebase existente (ingeniería inversa)
+i18n: true
+---
+
+# /especdev:reversa
+
+## Objetivo
+
+Analizar un codebase existente y extraer su arquitectura implícita: componentes, conexiones, flujos de datos, tecnologías y propiedad de código. Convierte código desorganizado en un mapa arquitectónico explícito.
+
+> Adaptado de DevilDev (lak7/devildev) — Reverse Architecture.
+
+## Uso
+
+```
+/especdev:reversa                          # Analizar el proyecto actual
+/especdev:reversa @ruta/al/proyecto        # Analizar un proyecto específico
+/especdev:reversa --profundidad superficial # Solo estructura de alto nivel
+/especdev:reversa --profundidad profunda    # Incluir flujo de datos y dependencias
+```
+
+## Por Qué Existe
+
+El 80% del trabajo de desarrollo es sobre codebases **existentes**, no greenfield. Antes de modificar un sistema, necesitas entender:
+- ¿Cuáles son los componentes principales?
+- ¿Cómo se conectan entre sí?
+- ¿Qué tecnologías usa cada componente?
+- ¿Dónde vive el código de cada componente?
+
+Sin esta herramienta, un agente IA empieza a modificar código **sin entender la arquitectura**, generando inconsistencias y duplicación.
+
+## Comportamiento
+
+### Paso 1: Escaneo Estructural
+
+```
+Escaneando proyecto...
+├── Detectando framework: Next.js 15 + TypeScript
+├── Identificando dependencias: 24 directas, 8 dev
+├── Mapeando estructura de directorios
+└── Analizando imports y exports
+```
+
+### Paso 2: Identificación de Componentes
+
+Aplica estas reglas (de DevilDev):
+
+1. **Solo componentes con evidencia** — No inventar lo que no existe
+2. **Test de valor de negocio** — ¿Un stakeholder no-técnico lo entendería?
+3. **Test de significancia** — ¿Si falla, requiere una solución técnica diferente?
+4. **Test de independencia** — ¿Se podría reemplazar con otra tecnología?
+
+### Paso 3: Mapeo de Propiedad de Código
+
+Para cada componente:
+
+```json
+{
+  "codeOwnership": {
+    "primaryImplementation": {
+      "directories": ["src/services/auth/"],
+      "files": ["src/middleware/jwt.ts"],
+      "confidence": 0.9,
+      "rationale": "Contiene toda la lógica de autenticación"
+    },
+    "supportingRelated": {
+      "directories": ["src/utils/crypto/"],
+      "confidence": 0.6,
+      "rationale": "Helpers de encriptación usados por auth"
+    },
+    "sharedDependencies": {
+      "files": ["src/db/prisma.ts"],
+      "confidence": 0.3,
+      "rationale": "Cliente de BD compartido con otros servicios"
+    }
+  }
+}
+```
+
+## Output
+
+```markdown
+# Arquitectura Extraída: mi-proyecto
+
+## Resumen
+E-commerce platform con 6 componentes principales.
+Stack: Next.js 15, PostgreSQL, Stripe, Redis.
+
+## Componentes
+
+### 1. 🛍️ Portal de Cliente
+- **Propósito:** Interfaz de usuario para compras
+- **Tecnologías:** React 19, Next.js App Router, TailwindCSS
+- **Código:** src/app/(store)/, src/components/
+- **Flujo de datos:**
+  - Envía: órdenes, búsquedas, preferencias
+  - Recibe: productos, precios, estado de pedido
+
+### 2. 🔐 Sistema de Autenticación
+- **Propósito:** Login, registro, sesiones
+- **Tecnologías:** NextAuth.js v5, JWT, bcrypt
+- **Código:** src/app/api/auth/, src/middleware.ts
+- **Flujo de datos:**
+  - Envía: tokens JWT, sesiones
+  - Recibe: credenciales, tokens OAuth
+
+### 3. 💳 Procesamiento de Pagos
+- **Propósito:** Cobros, reembolsos, suscripciones
+- **Tecnologías:** Stripe API v3, webhooks
+- **Código:** src/services/payment/, src/app/api/webhook/stripe/
+- **Flujo de datos:**
+  - Envía: cobros, reembolsos
+  - Recibe: confirmaciones, eventos Stripe
+
+### ... (más componentes)
+
+## Mapa de Conexiones
+
+```
+Portal de Cliente ──► Sistema de Auth ──► BD PostgreSQL
+       │                                        ▲
+       ▼                                        │
+Procesamiento de Pagos ─────────────────────────┘
+       │
+       ▼
+Servicio de Email
+```
+
+## Métricas
+- Complejidad ciclomática promedio: 4.2
+- Archivos sin tests: 12/48 (25%)
+- Dependencias desactualizadas: 3
+- Código muerto detectado: ~200 líneas
+```
+
+## Sincronización Automática
+
+Cuando hay un `git push`, la arquitectura se puede re-evaluar automáticamente:
+
+```yaml
+# WORKFLOW.md
+reversa:
+  auto_sync: true
+  trigger: "git push"
+  solo_archivos_cambiados: true  # Solo re-analiza lo que cambió
+```
+
+## Niveles de Profundidad
+
+| Nivel | Qué Incluye | Tokens Estimados |
+|-------|------------|-----------------|
+| Superficial | Estructura, framework, componentes principales | ~2,000 |
+| Media (default) | + conexiones, tecnologías, propiedad de código | ~5,000 |
+| Profunda | + flujo de datos, métricas, código muerto, tests | ~10,000 |

package/comandos/especdev/revisar.md

@@ -0,0 +1,231 @@
+---
+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
+
+## Regla Adversarial
+
+Inspirada en el framework BMAD: el reviewer DEBE encontrar al menos un hallazgo concreto en cada revisión.
+
+- Si el review produce **cero hallazgos**, se activa una segunda pasada obligatoria con instrucción explícita: "Re-analizar buscando específicamente: N+1 queries, race conditions, edge cases no testeados, datos sensibles en logs, y naming inconsistencies."
+- Si la segunda pasada también produce cero hallazgos, se debe incluir una justificación explícita de por qué el código es excepcionalmente limpio.
+- **Nunca** aprobar con "todo se ve bien" sin evidencia de análisis profundo.
+
+Esto combate la tendencia natural del LLM a aprobar trabajo propio sin challenge suficiente.