don-cheli-sdd 1.13.0

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

@@ -0,0 +1,302 @@
+---
+description: Modo Prueba de Concepto para validar viabilidad técnica antes de comprometer implementación completa
+i18n: true
+---
+
+# /especdev:poc
+
+## Objetivo
+
+Iniciar una Prueba de Concepto (PoC) para validar viabilidad técnica, explorar soluciones o demostrar una idea **antes** de comprometer una implementación completa. El PoC tiene reglas relajadas: prioriza velocidad y aprendizaje sobre calidad de producción.
+
+## Uso
+
+```
+/especdev:poc <descripción de lo que se quiere validar>
+/especdev:poc --hipotesis "<lo que quiero demostrar>"
+/especdev:poc --tiempo 2h                                # Limitar timebox (default: 4h)
+/especdev:poc --graduar                                  # Convertir PoC exitoso en feature real
+```
+
+## Cuándo Usar
+
+| Situación | PoC | Rápido | Completo |
+|-----------|-----|--------|----------|
+| "¿Se puede hacer X con esta librería?" | ✅ | | |
+| "¿Este enfoque escala?" | ✅ | | |
+| "Necesito una demo para el stakeholder" | ✅ | | |
+| "Corregir bug en auth" | | ✅ | |
+| "Implementar feature de pagos" | | | ✅ |
+| "¿WebSockets o SSE para real-time?" | ✅ | | |
+| "Migrar de REST a GraphQL, ¿vale la pena?" | ✅ | | |
+
+**Regla de oro:** Si la pregunta empieza con "¿se puede...?", "¿funciona...?" o "¿vale la pena...?" → es un PoC.
+
+## Diferencias con Modo Rápido y Completo
+
+| Aspecto | PoC | Rápido (N1) | Completo (N3) |
+|---------|-----|-------------|---------------|
+| **Objetivo** | Validar viabilidad | Entregar cambio | Entregar feature |
+| **Output** | Aprendizaje + demo | Código de producción | Sistema completo |
+| **TDD** | Opcional (solo tests de validación) | Obligatorio | Obligatorio |
+| **Coverage** | Sin mínimo | ≥85% | ≥85% |
+| **Lint/Types** | Relajado | Obligatorio | Obligatorio |
+| **Docs** | Veredicto + hallazgos | Descripción PR | spec.md + tech.md |
+| **Código** | Desechable (puede no mergearse) | Producción | Producción |
+| **Timebox** | Fijo (default 4h) | Variable | Variable |
+| **Constitución** | Solo Art. VII (Stop-Loss) | Completa | Completa |
+| **Stubs permitidos** | Sí (con marcador) | No | No |
+| **Contrato UI** | No | Si aplica | Si aplica |
+
+## Proceso (4 fases)
+
+### Fase 1: Hipótesis (10 min)
+
+Definir QUÉ se quiere validar y CÓMO se medirá el éxito/fracaso.
+
+```markdown
+## PoC: [título]
+
+**Hipótesis:** [lo que se quiere demostrar]
+**Criterio de éxito:** [cómo se sabe que funciona]
+**Criterio de fracaso:** [cuándo abandonar]
+**Timebox:** [tiempo máximo, default 4h]
+**Alcance:**
+  - Incluido: [qué se construirá]
+  - Excluido: [qué NO se construirá]
+
+**Preguntas a responder:**
+1. [pregunta técnica 1]
+2. [pregunta técnica 2]
+3. [pregunta técnica 3]
+```
+
+**Ejemplo:**
+
+```markdown
+## PoC: WebSockets vs SSE para notificaciones en tiempo real
+
+**Hipótesis:** WebSockets ofrece menor latencia que SSE para nuestro caso de uso
+  (notificaciones de cambio de estado de pedido, ~100 usuarios concurrentes).
+
+**Criterio de éxito:**
+  - WebSockets entrega notificaciones en < 50ms
+  - Conexión se mantiene estable por > 30 min
+  - Funciona detrás de nuestro reverse proxy (nginx)
+
+**Criterio de fracaso:**
+  - Latencia > 200ms
+  - Requiere cambio de infraestructura (nginx no soporta)
+  - Complejidad de implementación > 3x vs SSE
+
+**Timebox:** 3 horas
+
+**Alcance:**
+  - Incluido: Servidor WS básico, cliente simple, test de latencia
+  - Excluido: Auth, persistencia, UI bonita, reconexión automática
+
+**Preguntas a responder:**
+1. ¿Cuál es la latencia real de WS vs SSE en nuestro stack?
+2. ¿nginx necesita configuración especial para WS?
+3. ¿Cuántas conexiones concurrentes aguanta el servidor?
+```
+
+### Fase 2: Construir (80% del tiempo)
+
+Reglas relajadas para máxima velocidad:
+
+```
+✅ PERMITIDO en PoC:
+  - Hardcoded values (API keys en .env, datos mock)
+  - Código sin tipos estrictos
+  - Sin lint perfecto
+  - Console.log como debugging
+  - Dependencias sin evaluar alternativas
+  - Un solo archivo largo (sin modularizar)
+  - Estilos inline
+  - Sin manejo de errores exhaustivo
+
+❌ PROHIBIDO incluso en PoC:
+  - Credenciales en código (usar .env)
+  - Cambiar código de producción existente
+  - Commitear al branch principal
+  - Ignorar el timebox (Stop-Loss aplica)
+  - Concluir sin evidencia
+```
+
+**Ubicación del código PoC:**
+
+```
+poc/
+├── <nombre-poc>/
+│   ├── README.md          # Hipótesis + veredicto
+│   ├── src/               # Código del PoC
+│   ├── resultados/        # Screenshots, benchmarks, logs
+│   └── .env.example       # Variables requeridas (sin valores)
+```
+
+**Branch:** `poc/<nombre-poc>` (siempre desde la rama actual, nunca main)
+
+### Fase 3: Evaluar (10 min)
+
+Contra los criterios definidos en la hipótesis:
+
+```markdown
+## Evaluación del PoC
+
+### Resultados vs Criterios
+
+| Criterio | Resultado | Veredicto |
+|----------|-----------|-----------|
+| Latencia < 50ms | 12ms promedio | ✅ CUMPLE |
+| Estable > 30 min | 45 min sin desconexión | ✅ CUMPLE |
+| Funciona con nginx | Sí, con `proxy_set_header Upgrade` | ✅ CUMPLE |
+
+### Preguntas Respondidas
+
+1. **Latencia WS vs SSE:** WS = 12ms, SSE = 45ms (WS 3.7x más rápido)
+2. **nginx:** Requiere 3 líneas de config adicional (documentado)
+3. **Conexiones:** Servidor aguanta ~500 concurrentes con 256MB RAM
+
+### Hallazgos Inesperados
+- La librería `ws` tiene memory leak conocido en v8.16 (usar v8.17+)
+- SSE no funciona con HTTP/2 en nuestro setup actual
+
+### Evidencia
+- Benchmark: resultados/benchmark.json
+- Screenshot: resultados/latency-chart.png
+- Logs: resultados/stress-test.log
+```
+
+### Fase 4: Veredicto (5 min)
+
+Uno de 4 resultados posibles:
+
+```markdown
+## Veredicto: ✅ VIABLE — Proceder con implementación
+
+**Recomendación:** Usar WebSockets para notificaciones real-time.
+**Próximo paso:** /especdev:comenzar Implementar notificaciones real-time con WebSockets
+**Hallazgos a preservar:**
+  - Config nginx necesaria → guardar en hallazgos.md
+  - Usar ws@8.17+ (no 8.16) → guardar en hallazgos.md
+  - Benchmark como referencia → guardar en resultados/
+```
+
+| Veredicto | Significado | Acción |
+|-----------|-------------|--------|
+| ✅ **VIABLE** | Hipótesis confirmada, criterios cumplidos | Graduar a feature con `/especdev:poc --graduar` |
+| ⚠️ **VIABLE CON RESERVAS** | Funciona pero con limitaciones | Documentar limitaciones, decidir si proceder |
+| ❌ **NO VIABLE** | Hipótesis refutada | Documentar por qué, explorar alternativas |
+| 🔄 **INCONCLUSO** | Timebox agotado sin evidencia suficiente | Extender timebox o reformular hipótesis |
+
+## Graduación de PoC a Feature
+
+Cuando un PoC es VIABLE, se puede graduar a una feature real:
+
+```bash
+/especdev:poc --graduar
+```
+
+### Flujo de Graduación
+
+```
+PoC VIABLE
+  │
+  ├── 1. Extraer hallazgos → .especdev/hallazgos.md
+  ├── 2. Extraer decisiones técnicas → .especdev/memoria/decisiones.md
+  ├── 3. Crear propuesta desde PoC → /especdev:proponer (auto-generada)
+  ├── 4. Iniciar pipeline completo → /especdev:comenzar
+  │      (con contexto del PoC como input)
+  └── 5. Archivar código PoC → poc/_archivo/<nombre>/
+```
+
+**Importante:** El código del PoC **NO se reutiliza** directamente. Se reescribe con calidad de producción siguiendo el pipeline completo (TDD, constitución, puertas de calidad). El PoC informa las decisiones, no el código.
+
+## Timebox y Stop-Loss
+
+| Timebox | Acción |
+|---------|--------|
+| 50% del tiempo | Checkpoint: ¿avanzando hacia la respuesta? |
+| 75% del tiempo | Warning: empezar a consolidar hallazgos |
+| 100% del tiempo | ⛔ PARAR. Evaluar con lo que hay |
+| >100% (extendido) | Solo si el usuario lo autoriza explícitamente |
+
+**Regla:** Un PoC que no da respuesta en el timebox es un PoC mal definido, no un PoC que necesita más tiempo.
+
+## Integración con Pipeline
+
+```
+/especdev:poc → hipótesis + código + veredicto
+  ├── ✅ VIABLE → /especdev:poc --graduar → /especdev:proponer → pipeline normal
+  ├── ⚠️ CON RESERVAS → documentar → decisión del usuario
+  ├── ❌ NO VIABLE → documentar → explorar alternativa
+  └── 🔄 INCONCLUSO → reformular hipótesis → nuevo PoC
+```
+
+## Almacenamiento
+
+```
+poc/
+├── websockets-vs-sse/
+│   ├── README.md            # Hipótesis + veredicto
+│   ├── src/                 # Código PoC
+│   └── resultados/          # Evidencia
+├── graphql-migration/
+│   ├── README.md
+│   ├── src/
+│   └── resultados/
+└── _archivo/                # PoCs graduados o descartados
+    └── auth-biometrica/
+```
+
+## Ejemplo Completo
+
+```bash
+/especdev:poc --hipotesis "Podemos usar SQLite en vez de PostgreSQL para el MVP"
+
+=== PoC: SQLite para MVP ===
+
+📋 Fase 1: Hipótesis (2 min)
+  Hipótesis: SQLite es suficiente para MVP (< 100 usuarios, < 10K registros)
+  Criterio de éxito: CRUD funciona, queries < 10ms, datos persisten
+  Criterio de fracaso: Concurrencia falla, queries > 100ms
+  Timebox: 2 horas
+
+🔨 Fase 2: Construir (1h 40min)
+  ✅ Setup SQLite con Prisma
+  ✅ Migración de schema existente
+  ✅ CRUD básico funcionando
+  ✅ Test de concurrencia (10 escrituras paralelas)
+
+📊 Fase 3: Evaluar (10 min)
+  ✅ CRUD: funciona idéntico a PostgreSQL
+  ✅ Queries: 2-5ms (vs 5-15ms en PG local)
+  ⚠️ Concurrencia: WAL mode soporta 10 escrituras paralelas
+  ❌ Limitación: Sin full-text search nativo
+
+📝 Fase 4: Veredicto
+  ⚠️ VIABLE CON RESERVAS
+  - Funciona para MVP si no necesitamos full-text search
+  - Migrar a PostgreSQL será necesario antes de escalar
+  - Recomendación: usar SQLite para MVP, planear migración para v2
+```
+
+## Modelo Recomendado
+
+| Paso | Modelo | Razón |
+|------|--------|-------|
+| Hipótesis | Haiku | Solo estructurar la pregunta |
+| Construir | Sonnet | Código funcional rápido |
+| Evaluar | Haiku | Comparar contra criterios |
+| Veredicto | Haiku | Resumir resultados |
+
+## Guardrails
+
+- **Nunca** commitear al branch principal
+- **Nunca** modificar código de producción existente
+- **Nunca** exceder el timebox sin autorización explícita
+- **Nunca** reutilizar código PoC directamente en producción (graduar primero)
+- **Siempre** definir hipótesis y criterios ANTES de construir
+- **Siempre** documentar el veredicto con evidencia
+- **Siempre** archivar PoCs completados (no dejar código abandonado)

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