don-cheli-sdd 1.13.0

package/comandos/especdev/detectar-ambiguedad.md

@@ -0,0 +1,81 @@
+---
+description: Detectar ambigüedades y contradicciones en specs de forma exhaustiva
+i18n: true
+---
+
+# /especdev:detectar-ambiguedad
+
+## Objetivo
+
+Escanear specs en busca de ambigüedades, contradicciones, requisitos implícitos y campos faltantes. Va más allá de la clarificación básica — es un análisis exhaustivo de la calidad de la spec.
+
+> Basado en la práctica de MELI: "La ambigüedad es el bottleneck #1 del AI coding."
+
+## Uso
+
+```
+/especdev:detectar-ambiguedad @specs/features/<dominio>/<Feature>.feature
+/especdev:detectar-ambiguedad --todos   # Escanear todas las specs activas
+```
+
+## Qué Detecta
+
+### 1. Ambigüedades Lingüísticas
+- Pronombres sin referente claro ("esto se envía", "eso se valida")
+- Cuantificadores vagos ("algunos", "varios", "muchos")
+- Verbos pasivos sin sujeto ("será procesado", "se debe validar")
+
+### 2. Contradicciones Internas
+- Escenario A dice "email obligatorio", Escenario B no lo valida
+- Plan dice "async", tasks dice "sync"
+- Schema dice `NOT NULL`, spec no tiene escenario de validación
+
+### 3. Requisitos Implícitos No Documentados
+- "El usuario se registra" → ¿Qué pasa con confirmación por email?
+- "Se guarda en BD" → ¿Qué campos son obligatorios?
+- "Se envía notificación" → ¿A quién? ¿Cuándo? ¿Cómo?
+
+### 4. Gaps de Cobertura
+- Happy path sin sad path correspondiente
+- Campos en DBML sin validación en Gherkin
+- Endpoints sin manejo de errores
+
+## Output
+
+```markdown
+=== Análisis de Ambigüedad ===
+
+Feature: GestionarPedidos.feature
+Score de Claridad: 72/100
+
+## 🔴 Contradicciones (3)
+1. Línea 15: "el pedido se crea" vs Línea 42: "el pedido requiere aprobación"
+   → ¿Se crea directo o necesita aprobación?
+2. Línea 23: campo "estado" acepta "activo" vs DBML: enum no incluye "activo"
+3. Escenario 3 y Escenario 7 usan distinto formato de fecha
+
+## 🟡 Ambigüedades (5)
+1. Línea 8: "se notifica al usuario" → ¿email? ¿push? ¿in-app?
+2. Línea 31: "se valida el pago" → ¿qué proveedor? ¿qué criterios?
+3. Línea 45: "datos del cliente" → ¿cuáles exactamente?
+4. Línea 52: "en tiempo razonable" → ¿cuánto es razonable?
+5. Línea 67: "se procesa" → ¿quién? ¿cuándo? ¿cómo?
+
+## 🟢 Requisitos Implícitos Detectados (2)
+1. No hay escenario para cancelar pedido después de pago
+2. No hay manejo de timeout en validación de pago
+
+## Recomendaciones
+- Resolver contradicciones ANTES de avanzar a fase Plan
+- Score mínimo recomendado: 85/100
+- Score actual: 72/100 → NO AVANZAR
+```
+
+## Score de Claridad
+
+| Rango | Clasificación | Acción |
+|-------|--------------|--------|
+| 90-100 | Cristalino | ✅ Avanzar |
+| 80-89 | Claro | ✅ Avanzar con notas |
+| 70-79 | Aceptable | ⚠️ Resolver ambigüedades primero |
+| <70 | Ambiguo | ❌ NO avanzar, reescribir |

package/comandos/especdev/diagnostico.md

@@ -0,0 +1,92 @@
+---
+description: Verificar la salud del setup de Don Cheli en el proyecto actual
+i18n: true
+---
+
+# /especdev:diagnostico
+
+## Objetivo
+
+Verificar que el setup de Don Cheli en el proyecto está completo y funcional. Detecta archivos faltantes, configuración inconsistente y problemas comunes.
+
+## Uso
+
+```
+/especdev:diagnostico
+```
+
+## Comportamiento
+
+Ejecutar verificaciones en 4 categorías:
+
+### 1. Estructura .especdev/
+
+```
+Verificando .especdev/...
+  ✅ config.yaml existe y es válido
+  ✅ estado.md existe
+  ✅ plan.md existe
+  ⚠️ hallazgos.md no existe (se creará al explorar)
+  ✅ progreso.md existe
+  ✅ memoria/ directorio existe
+```
+
+### 2. Configuración
+
+```
+Verificando configuración...
+  ✅ proyecto.nombre definido: "mi-proyecto"
+  ✅ proyecto.tipo válido: "servicio"
+  ✅ modelos.default definido: "sonnet"
+  ⚠️ idioma no definido (usando default: "es")
+```
+
+### 3. Entorno
+
+```
+Verificando entorno...
+  ✅ Git inicializado
+  ✅ Branch actual: feature/auth
+  ✅ Docker disponible (para /especdev:implementar)
+  ⚠️ Docker Compose no encontrado (opcional)
+  ✅ Node/Python/Go detectado (según stack)
+  ✅ Linter configurado
+  ✅ Tests configurados
+```
+
+### 4. Pipeline
+
+```
+Verificando pipeline...
+  ✅ specs/features/ directorio existe
+  ✅ 3 features encontradas (2 @lista, 1 @borrador)
+  ⚠️ specs/db_schema/ no existe (se creará al especificar)
+  ✅ Constitución presente (reglas/constitucion.md)
+```
+
+## Output
+
+```markdown
+## Diagnóstico Don Cheli: mi-proyecto
+
+| Categoría | Estado | Problemas |
+|-----------|--------|-----------|
+| Estructura | ✅ OK | 0 |
+| Configuración | ⚠️ Warning | 1 warning |
+| Entorno | ⚠️ Warning | 1 warning |
+| Pipeline | ✅ OK | 0 |
+
+### Warnings
+1. `idioma` no definido en config.yaml → agregar `idioma: "es"`
+2. Docker Compose no encontrado → instalar para usar `/especdev:implementar`
+
+### Resultado: ✅ SALUDABLE (2 warnings menores)
+```
+
+## Resultados Posibles
+
+| Resultado | Significado |
+|-----------|-------------|
+| ✅ **SALUDABLE** | Todo funciona, warnings son opcionales |
+| ⚠️ **FUNCIONAL** | Funciona pero con limitaciones |
+| ❌ **REQUIERE ATENCIÓN** | Archivos críticos faltantes, ejecutar `/especdev:iniciar` |

package/comandos/especdev/dise/303/261ar.md

@@ -0,0 +1,74 @@
+---
+description: Diseño técnico con decisiones de arquitectura documentadas
+i18n: true
+---
+
+# /especdev:diseñar
+
+## Objetivo
+
+Crear un documento de diseño técnico entre la planificación y el desglose de tareas. Documenta decisiones de arquitectura, trade-offs evaluados, y el diseño detallado del sistema.
+
+> Adaptado de `sdd-design` de Gentle-AI — separa la planificación del diseño técnico.
+
+## Uso
+
+```
+/especdev:diseñar @specs/features/<dominio>/<Feature>.plan.md
+```
+
+## Diferencia con planificar-tecnico
+
+| `/especdev:planificar-tecnico` | `/especdev:diseñar` |
+|-------------------------------|---------------------|
+| Blueprint: contratos API, modelos, servicios | Decisiones de arquitectura y trade-offs |
+| QUÉ vamos a construir | CÓMO y POR QUÉ así |
+| Rápido, estructurado | Profundo, con análisis |
+
+## Output
+
+```markdown
+# Diseño Técnico: Sistema de Autenticación OAuth
+
+## Decisiones de Arquitectura
+
+### ADR-001: Strategy Pattern para Providers
+- **Estado:** Aceptada
+- **Contexto:** Necesitamos soportar Google, GitHub, y posiblemente más
+- **Opciones evaluadas:**
+  1. If/else por provider → No extensible
+  2. Strategy Pattern → Extensible, testeable ✅
+  3. Plugin system → Over-engineering para esta fase
+- **Consecuencias:** Cada provider es una clase independiente
+
+### ADR-002: Tokens en BD vs Redis
+- **Estado:** Aceptada
+- **Decisión:** BD con TTL automático
+- **Razón:** No queremos agregar Redis como dependencia solo para tokens
+
+## Diagramas
+
+### Flujo de Autenticación
+```
+Usuario → Redirect a Google → Callback → Verificar Token
+    → Buscar/Crear usuario local → Generar JWT interno → Responder
+```
+
+## Complejidad
+| Componente | Complejidad | Notas |
+|-----------|-------------|-------|
+| OAuthProvider interface | Baja | Strategy pattern simple |
+| GoogleProvider | Media | API de Google bien documentada |
+| Account linking | Alta | Lógica de merge de cuentas |
+| Token refresh | Media | Background job necesario |
+
+## Estado: APROBADO PARA IMPLEMENTACIÓN
+```
+
+## Pipeline Actualizado (9 Fases)
+
+```
+explorar → proponer → especificar → clarificar
+→ planificar-tecnico → diseñar → desglosar
+→ implementar → revisar
+```

package/comandos/especdev/doctor.md

@@ -0,0 +1,78 @@
+---
+description: Diagnosticar y reparar problemas del framework, git y entorno
+i18n: true
+---
+
+# /especdev:doctor
+
+## Objetivo
+
+Detectar y reparar automáticamente problemas comunes del framework, estado de git, worktrees, y entorno de desarrollo. Es el "médico" del proyecto.
+
+## Uso
+
+```
+/especdev:doctor                  # Diagnóstico completo + reparación automática
+/especdev:doctor --solo-diagnostico   # Solo reportar, no reparar
+/especdev:doctor --git            # Solo problemas de git
+/especdev:doctor --framework      # Solo problemas del framework
+```
+
+## Checks Realizados
+
+### Git Health
+| Check | Detecta | Auto-repair |
+|-------|---------|-------------|
+| Detached HEAD | `git status` sin branch | `git checkout <branch>` |
+| Stale lock files | `.git/index.lock` huérfano | Eliminar si proceso no existe |
+| Worktrees huérfanos | Worktrees sin directorio de trabajo | `git worktree prune` |
+| Branches huérfanas | Branches sin remote y sin actividad > 30 días | Listar para limpieza manual |
+| Merge conflicts sin resolver | `<<<` markers en archivos tracked | Listar archivos afectados |
+| Unstaged changes perdidos | Archivos modificados no commiteados | Warning + sugerir stash |
+| Default branch detection | main vs master vs develop | Auto-detectar y configurar |
+
+### Framework Health
+| Check | Detecta | Auto-repair |
+|-------|---------|-------------|
+| Archivos .especdev faltantes | estado.md, plan.md, etc. no existen | Regenerar desde plantilla |
+| config.yaml corrupto | YAML inválido | Regenerar con valores default |
+| Versión desactualizada | VERSION < latest | Notificar actualización disponible |
+| Capturas no procesadas | capturas.md con > 10 items pendientes | Warning |
+| Sesión huérfana | Lock de sesión sin proceso activo | Limpiar lock |
+| Habilidades faltantes | Referencia a habilidad que no existe | Warning + listar |
+
+### Environment Health
+| Check | Detecta | Auto-repair |
+|-------|---------|-------------|
+| Node/Python no instalado | Runtime requerido no disponible | Warning con instrucciones |
+| Docker no corriendo | Docker daemon parado | Warning |
+| Puerto ocupado | Puerto 3000/5432/6379 en uso | Listar procesos |
+| .env faltante | No existe .env pero sí .env.example | Copiar .env.example → .env |
+| Dependencias desactualizadas | package-lock.json más viejo que package.json | `npm install` |
+
+## Output
+
+```
+🏥 Don Cheli Doctor — Diagnóstico Completo
+
+Git Health:
+  ✅ Branch: main (up to date with origin)
+  ✅ No stale locks
+  ⚠️  2 worktrees huérfanos detectados → limpiados
+  ✅ No merge conflicts
+
+Framework Health:
+  ✅ .especdev/ completo (5/5 archivos)
+  ✅ config.yaml válido
+  ⚠️  3 capturas pendientes de procesar
+  ✅ Versión 1.7.0 (última)
+
+Environment:
+  ✅ Node v22.2.0
+  ✅ Docker running
+  ⚠️  Puerto 5432 ocupado (postgres ya corriendo)
+  ✅ .env existe
+
+Resultado: ✅ SALUDABLE (2 warnings, 0 errores)
+Reparaciones: 1 aplicada (worktrees limpiados)
+```

package/comandos/especdev/donde-estoy.md

@@ -0,0 +1,32 @@
+---
+description: Test rápido de 5 preguntas para verificar contexto
+i18n: true
+---
+
+# /especdev:donde-estoy
+
+## Objetivo
+
+Ejecutar un test rápido de 5 preguntas para verificar que el contexto de trabajo está completo.
+
+## Uso
+
+```
+/especdev:donde-estoy
+```
+
+## Las 5 Preguntas
+
+| # | Pregunta | Fuente |
+|---|----------|--------|
+| 1 | ¿Dónde estoy? | `estado.md` |
+| 2 | ¿A dónde voy? | `plan.md` |
+| 3 | ¿Cuál es la meta? | `config.yaml` |
+| 4 | ¿Qué he aprendido? | `hallazgos.md` |
+| 5 | ¿Qué he hecho? | `progreso.md` |
+
+## Interpretación
+
+- ✅ 5/5 → Listo para continuar
+- ⚠️ 3-4/5 → Proceder con precaución
+- ❌ 0-2/5 → Ejecutar `/especdev:iniciar --reparar`

package/comandos/especdev/especificar.md

@@ -0,0 +1,189 @@
+---
+description: Crear especificación Gherkin desde un requerimiento con schema DBML auto-generado
+i18n: true
+---
+
+# /especdev:especificar
+
+## Objetivo
+
+Convertir un requerimiento en lenguaje natural a una especificación Gherkin estructurada (`.feature`), incluyendo auto-generación de schema DBML provisional si no existe.
+
+> Mejorado con el ciclo de vida DBML de Specular (constitution.md §I-B)
+> Alineado con spec-kit (github/spec-kit) — prioridades P1/P2/P3+, criterios de éxito y marcadores de clarificación
+
+## Uso
+
+```
+/especdev:especificar Tipo: <COMANDO|CONSULTA|EVENTO> Feature: <dominio/Nombre> Dominio: <dominio> Requerimiento: <descripción> Contexto: @<archivo-referencia>
+```
+
+## Comportamiento
+
+1. **Verificar** si existe `specs/db_schema/<dominio>.dbml`
+   - Si **NO existe** → Auto-generar DBML `@provisional` con campos inferidos del requerimiento
+   - Si **existe y está ratificado** → Usar como referencia, agregar nuevos campos como `@provisional`
+2. **Analizar** el requerimiento proporcionado
+3. **Identificar** actores, acciones y resultados esperados
+4. **Categorizar** escenarios por prioridad (P1/P2/P3+)
+5. **Generar** escenarios Gherkin con Dado/Cuando/Entonces
+6. **Usar** los nombres de campo EXACTOS del DBML en los escenarios
+7. **Marcar** requisitos ambiguos con `[NECESITA CLARIFICACIÓN]`
+8. **Definir** criterios de éxito medibles y agnósticos de tecnología
+9. **Crear** archivo `.feature` en `specs/features/<dominio>/` con tag `@borrador`
+10. **Incluir** edge cases y escenarios de error
+11. **Generar** checklist de requisitos vacía (`requisitos.md`)
+
+## Output
+
+### Schema DBML (auto-generado si no existe)
+
+```dbml
+// specs/db_schema/usuario.dbml
+// @provisional — Auto-generado por /especdev:especificar
+
+Table usuario @provisional {
+  id uuid [pk, default: `gen_random_uuid()`]
+  email varchar(255) [unique, not null]
+  password_hash varchar(255) [not null]
+  nombre varchar(100) [not null]
+  created_at timestamp [not null, default: `now()`]
+}
+```
+
+### Spec Gherkin
+
+```gherkin
+# specs/features/usuario/CrearUsuario.feature
+# Estado: @borrador
+# Rama: feature/crear-usuario
+# Creado: 2026-03-21
+
+@borrador
+Feature: Crear Usuario
+  Como usuario nuevo
+  Quiero registrarme con email y contraseña
+  Para poder acceder al sistema
+
+  ## Prioridad P1: Camino Crítico (Must Have)
+
+  @P1
+  Escenario: Registro exitoso
+    # Historia: Usuario se registra con datos válidos
+    Dado que no existe un usuario con email "test@ejemplo.com"
+    Cuando envío una solicitud de registro con:
+      | campo    | valor            |
+      | email    | test@ejemplo.com |
+      | password | MiClave123!      |
+      | nombre   | Test User        |
+    Entonces el usuario se crea exitosamente
+    Y recibo un token de autenticación
+
+  @P1
+  Escenario: Email duplicado
+    Dado que existe un usuario con email "test@ejemplo.com"
+    Cuando envío una solicitud de registro con email "test@ejemplo.com"
+    Entonces la creación debería fallar
+    Y el mensaje de error debería indicar "El email ya está registrado"
+
+  ## Prioridad P2: Importante (Should Have)
+
+  @P2
+  Escenario: Campo obligatorio vacío
+    Cuando envío una solicitud de registro con:
+      | campo    | valor            |
+      | email    | test@ejemplo.com |
+      | password | MiClave123!      |
+      | nombre   |                  |
+    Entonces la creación debería fallar
+    Y el mensaje de error debería indicar "El nombre es obligatorio"
+
+  @P2
+  Escenario: Contraseña débil
+    # [NECESITA CLARIFICACIÓN] ¿Cuáles son los requisitos exactos de fortaleza de contraseña?
+    Cuando envío una solicitud de registro con:
+      | campo    | valor            |
+      | email    | test@ejemplo.com |
+      | password | 123              |
+      | nombre   | Test User        |
+    Entonces la creación debería fallar
+    Y el mensaje de error debería indicar "La contraseña no cumple los requisitos"
+
+  ## Prioridad P3+: Deseable (Nice to Have)
+
+  @P3
+  Escenario: Registro con proveedor OAuth
+    # [NECESITA CLARIFICACIÓN] ¿Se soporta OAuth? ¿Qué proveedores?
+    Dado que el usuario tiene una cuenta de Google
+    Cuando inicia registro con Google OAuth
+    Entonces el usuario se crea con los datos del proveedor
+```
+
+### Criterios de Éxito
+
+Los criterios se incluyen al final del `.feature` como comentarios estructurados:
+
+```gherkin
+  # === CRITERIOS DE ÉXITO ===
+  # Experiencia de Usuario:
+  #   - El registro se completa en menos de 3 pasos
+  #   - Los errores de validación son claros y accionables
+  # Rendimiento:
+  #   - El registro responde en < 500ms (p95)
+  # Fiabilidad:
+  #   - 99.9% de los registros válidos se completan exitosamente
+  # Negocio:
+  #   - Tasa de conversión de registro > 60%
+
+  # === NECESITA CLARIFICACIÓN ===
+  # 1. ¿Cuáles son los requisitos de fortaleza de contraseña? (min longitud, caracteres especiales)
+  # 2. ¿Se soporta registro con OAuth? ¿Qué proveedores?
+  # 3. ¿El email de bienvenida es síncrono o asíncrono?
+```
+
+## Categorización de Prioridades
+
+| Prioridad | Significado | Criterio |
+|-----------|-------------|----------|
+| **P1** | Camino Crítico (Must Have) | Sin esto, la feature no funciona |
+| **P2** | Importante (Should Have) | Necesario para calidad de producción |
+| **P3+** | Deseable (Nice to Have) | Mejora la experiencia pero no bloquea |
+
+**Regla:** Todo spec DEBE tener al menos 1 escenario P1 (happy path) y 1 escenario P1 (sad path).
+
+## Marcadores de Clarificación
+
+Usar `[NECESITA CLARIFICACIÓN]` inline cuando:
+- Un requisito es ambiguo
+- Falta información para definir el comportamiento exacto
+- Hay múltiples interpretaciones posibles
+
+Estos marcadores se resuelven durante `/especdev:clarificar` y DEBEN estar vacíos antes de avanzar a `/especdev:planificar-tecnico`.
+
+## Artefactos Generados
+
+| Artefacto | Ruta | Condición |
+|-----------|------|-----------|
+| Schema DBML | `specs/db_schema/<dominio>.dbml` | Solo si no existe |
+| Spec Gherkin | `specs/features/<dominio>/<Feature>.feature` | Siempre |
+| Checklist | `specs/features/<dominio>/requisitos.md` | Siempre (vacía) |
+
+## Pipeline Completo
+
+```
+/especdev:especificar → .feature + .dbml(@provisional)
+→ /especdev:clarificar → .feature(@lista) + Auto-QA
+→ /especdev:planificar-tecnico → .plan.md (ratifica @provisional)
+→ /especdev:desglosar → .tasks.md
+→ /especdev:implementar → código + tests en Docker
+→ /especdev:revisar → review.md + test-report.html
+```
+
+## Puerta de Calidad
+
+Este comando produce el tag `@borrador`. El spec DEBE pasar por `/especdev:clarificar` para obtener el tag `@lista` antes de avanzar a la fase Plan.
+
+**Criterios de la Puerta 1 (Completitud de Spec):**
+- Cada prioridad P1 tiene al menos un happy path y un sad path
+- Criterios de éxito definidos (al menos 2 medibles)
+- Todos los marcadores `[NECESITA CLARIFICACIÓN]` identificados (se resuelven en clarificar)

package/comandos/especdev/estado.md

@@ -0,0 +1,46 @@
+---
+description: Mostrar el estado actual del proyecto Don Cheli
+i18n: true
+---
+
+# /especdev:estado
+
+## Objetivo
+
+Mostrar un resumen del estado actual del proyecto según los archivos de `.especdev/`.
+
+## Uso
+
+```
+/especdev:estado
+```
+
+## Comportamiento
+
+1. **Leer** `.especdev/config.yaml` — nombre y tipo de proyecto
+2. **Leer** `.especdev/estado.md` — fase actual y progreso
+3. **Leer** `.especdev/plan.md` — fases restantes
+4. **Generar** resumen visual
+
+## Output
+
+```
+=== Estado del Proyecto ===
+
+📋 Proyecto: api-pagos (servicio)
+📍 Fase: 3/7 (Diseño)
+📊 Progreso: 40%
+🕐 Última actualización: 2026-03-21 15:30
+
+Tareas pendientes: 5
+Hallazgos: 3 registrados
+Sesiones: 4 completadas
+
+Velocidad:
+- Sesiones completadas: 4
+- Duración promedio: 2.5h
+- Fases completadas: 2/7
+- Tiempo restante estimado: ~15h
+
+Próximo paso: Completar diseño de base de datos
+```