don-cheli-sdd 1.13.0

package/comandos/especdev/estimar.md

@@ -0,0 +1,141 @@
+---
+description: Generar estimados de desarrollo usando múltiples modelos de estimación
+i18n: true
+---
+
+# /especdev:estimar
+
+## Objetivo
+
+Generar estimados de desarrollo profesionales usando múltiples modelos de estimación en paralelo, produciendo un rango optimista/esperado/pesimista con análisis de riesgos.
+
+## Uso
+
+```
+/especdev:estimar <prd.md | feature | tarea>
+/especdev:estimar --modelo <puntos-funcion|poker|cocomo|historico>
+/especdev:estimar --formato <resumen|detallado|ejecutivo>
+```
+
+## Modelos de Estimación
+
+### 1. Puntos de Función
+
+Evalúa la complejidad funcional de cada feature:
+
+| Componente | Simple | Medio | Complejo |
+|-----------|--------|-------|----------|
+| Entrada externa | 3 PF | 4 PF | 6 PF |
+| Salida externa | 4 PF | 5 PF | 7 PF |
+| Consulta externa | 3 PF | 4 PF | 6 PF |
+| Archivo lógico | 7 PF | 10 PF | 15 PF |
+| Interfaz externa | 5 PF | 7 PF | 10 PF |
+
+**Conversión:** PF total × Factor de productividad = Horas estimadas
+
+### 2. Planning Poker IA
+
+Tres "agentes" independientes estiman la misma tarea:
+
+```
+Agente Optimista: Asume el mejor escenario, experiencia previa
+Agente Realista: Considera complejidad típica, imprevistos menores
+Agente Pesimista: Incluye riesgos, curva de aprendizaje, dependencias
+
+Estimado final = (Optimista + 4×Realista + Pesimista) / 6
+```
+
+### 3. COCOMO Simplificado
+
+Basado en líneas de código estimadas:
+
+```
+Esfuerzo (personas-mes) = a × (KLOC)^b
+
+Donde:
+- KLOC = Miles de líneas de código estimadas
+- a, b = Coeficientes según tipo de proyecto
+  - Orgánico (simple): a=2.4, b=1.05
+  - Semi-empotrado: a=3.0, b=1.12
+  - Empotrado (complejo): a=3.6, b=1.20
+```
+
+### 4. Estimación Histórica
+
+Compara con tareas similares completadas previamente:
+
+```
+1. Buscar en .especdev/historial/ tareas similares
+2. Comparar alcance, tecnología, complejidad
+3. Ajustar por diferencias
+4. Aplicar factor de confianza
+```
+
+## Comportamiento
+
+1. **Leer** el input (PRD, feature o tarea)
+2. **Desglosar** en componentes estimables
+3. **Aplicar** los 4 modelos de estimación
+4. **Calcular** consenso y rango
+5. **Identificar** riesgos que afectan la estimación
+6. **Generar** documento de estimado
+
+## Output
+
+Genera archivo `estimado-[fecha].md`:
+
+```markdown
+# Estimado de Desarrollo: [Nombre del Proyecto]
+
+## Resumen Ejecutivo
+
+| Métrica | Valor |
+|---------|-------|
+| **Esfuerzo total** | 15-22 días/persona |
+| **Complejidad** | Media-Alta |
+| **Confianza** | 70% |
+| **Modelo dominante** | Planning Poker IA |
+
+## Desglose por Feature
+
+| Feature | Optimista | Esperado | Pesimista | Riesgo |
+|---------|-----------|----------|-----------|--------|
+| Autenticación | 3d | 5d | 8d | Medio |
+| API REST | 2d | 3d | 5d | Bajo |
+| Interfaz UI | 5d | 8d | 12d | Alto |
+| Base de datos | 1d | 2d | 3d | Bajo |
+
+## Detalle por Modelo
+
+### Puntos de Función: 18 días
+### Planning Poker IA: 16 días (consenso)
+### COCOMO: 20 días
+### Histórico: N/A (sin datos previos)
+
+## Riesgos que Afectan la Estimación
+
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|-------------|---------|------------|
+| API externa | 40% | +3 días | Mockear temprano |
+| Requisitos ambiguos | 30% | +2 días | Clarificar en Fase 1 |
+| Curva aprendizaje | 20% | +2 días | Spike técnico |
+
+## Supuestos Clave
+
+- Desarrollador con experiencia en la tecnología
+- Requisitos estables durante el desarrollo
+- Infraestructura disponible
+- Sin dependencias externas bloqueantes
+
+## Recomendación
+
+Usar estimado **esperado** (18 días) con buffer de 20% para imprevistos
+→ **Total recomendado: 22 días/persona**
+```
+
+## Integración
+
+- Se puede ejecutar en cualquier fase del proyecto
+- Los estimados se guardan en `.especdev/estimados/`
+- El modelo histórico aprende de estimaciones previas vs. tiempo real
+- Se puede re-estimar cuando cambia el alcance

package/comandos/especdev/explorar.md

@@ -0,0 +1,175 @@
+---
+description: Explorar e investigar el codebase antes de proponer cambios
+i18n: true
+---
+
+# /especdev:explorar
+
+## Objetivo
+
+Investigar el codebase existente antes de comprometer un cambio. Entender la arquitectura, patrones, convenciones y dependencias ANTES de modificar nada.
+
+> Adaptado de `sdd-explore` de Gentle-AI — fase que Don Cheli no tenía.
+> Mejorado con Modo Supuestos de Get Shit Done (gsd-build/get-shit-done).
+
+## Uso
+
+```
+/especdev:explorar <área o concepto a investigar>
+/especdev:explorar --profundidad <superficial|media|profunda>
+/especdev:explorar --modo supuestos                            # Modo Supuestos (nuevo)
+```
+
+## Dos Modos de Exploración
+
+### Modo Interactivo (default)
+
+El modo original: el agente investiga y hace preguntas al usuario.
+
+**Flujo:** Escanear → Preguntar → Documentar → Repetir (15-20 interacciones típicas)
+
+### Modo Supuestos (nuevo)
+
+El agente analiza el codebase, forma **supuestos con evidencia**, y el usuario solo confirma o corrige.
+
+**Flujo:** Analizar → Presentar supuestos → Usuario confirma/corrige (2-4 interacciones típicas)
+
+**Cuándo usar cada modo:**
+
+| Situación | Modo recomendado |
+|-----------|------------------|
+| Proyecto nuevo sin código | Interactivo |
+| Codebase existente con >10 archivos | **Supuestos** |
+| Usuario conoce bien el proyecto | **Supuestos** |
+| Dominio complejo o desconocido | Interactivo |
+| Quiero terminar rápido | **Supuestos** |
+
+## Comportamiento — Modo Interactivo
+
+1. **Escanear** estructura del proyecto (directorios, archivos clave)
+2. **Identificar** stack tecnológico (package.json, requirements.txt, etc.)
+3. **Mapear** patrones existentes (naming, estructura, imports)
+4. **Detectar** convenciones (estilo de código, formato de tests)
+5. **Documentar** hallazgos en `.especdev/hallazgos.md`
+
+## Comportamiento — Modo Supuestos
+
+### Paso 1: Análisis Silencioso
+
+El agente analiza 5-15 archivos relevantes **sin preguntar nada**:
+
+```
+Analizando codebase...
+├── Archivos escaneados: 12
+├── Patrones detectados: 8
+├── Convenciones inferidas: 5
+└── Supuestos formados: 7
+```
+
+### Paso 2: Presentar Supuestos
+
+Cada supuesto incluye **evidencia** y **nivel de confianza**:
+
+```markdown
+## Supuestos sobre el Módulo de Autenticación
+
+### S1: El proyecto usa Repository Pattern [ALTA confianza]
+**Evidencia:**
+- `src/repositories/user_repo.py` existe con interface definida (línea 5-15)
+- `src/services/auth_service.py` recibe repositorio por inyección (línea 8)
+- 3 repositorios más siguen el mismo patrón
+
+**Supuesto:** Los nuevos componentes DEBEN seguir Repository Pattern con DI.
+→ ¿Correcto? [sí/no/matiz]
+
+---
+
+### S2: Los tests de integración usan base de datos real [MEDIA confianza]
+**Evidencia:**
+- `tests/conftest.py` crea una BD de test (línea 12-20)
+- No hay mocks de BD en `tests/integration/`
+- Pero `tests/unit/` sí usa mocks
+
+**Supuesto:** Integration tests = BD real. Unit tests = mocks.
+→ ¿Correcto? [sí/no/matiz]
+
+---
+
+### S3: No hay sistema de permisos/roles [ALTA confianza]
+**Evidencia:**
+- No existe archivo de roles ni middleware de permisos
+- El JWT solo contiene `user_id`, sin `role` ni `permissions`
+- No hay tests relacionados con autorización
+
+**Supuesto:** La feature nueva NO necesita considerar roles/permisos.
+→ ¿Correcto? [sí/no/matiz]
+```
+
+### Paso 3: Confirmar/Corregir
+
+El usuario responde con:
+- **"sí"** → Supuesto confirmado
+- **"no"** → Supuesto rechazado (el agente pide la corrección)
+- **"matiz: ..."** → Parcialmente correcto (el agente ajusta)
+
+### Paso 4: Generar Hallazgos
+
+Los supuestos confirmados se documentan en `.especdev/hallazgos.md` con la misma estructura que el modo interactivo, pero **más rápido**.
+
+## Niveles de Confianza
+
+| Nivel | Significado | Evidencia requerida |
+|-------|-------------|---------------------|
+| **ALTA** | Patrón consistente en 3+ archivos | ≥3 archivos coinciden |
+| **MEDIA** | Patrón en 1-2 archivos o con excepciones | 1-2 archivos, con contraejemplos |
+| **BAJA** | Inferencia sin evidencia directa | Sin archivos que lo demuestren directamente |
+
+**Regla:** Solo presentar supuestos con confianza MEDIA o ALTA. Los de confianza BAJA se descartan o se convierten en preguntas abiertas.
+
+## Output
+
+```markdown
+## Exploración: Módulo de Autenticación
+
+### Stack Detectado
+- Framework: FastAPI 0.115
+- ORM: SQLAlchemy 2.0
+- Auth: JWT con python-jose
+- Tests: pytest + pytest-asyncio
+
+### Estructura
+app/
+├── services/auth_service.py  (342 líneas)
+├── routers/auth.py           (89 líneas)
+├── models/user.py            (45 líneas)
+└── middleware/jwt.py          (67 líneas)
+
+### Convenciones Encontradas
+- Servicios usan async/await
+- Repository pattern con inyección de dependencias
+- Tests unitarios en tests/unit/, integración en tests/integration/
+- Naming: snake_case para todo
+
+### Funcionalidad Existente Relevante
+- `auth_service.create_user()` ya existe
+- `jwt.verify_token()` ya existe
+- `UserRepository` interface definida
+
+### Supuestos Confirmados (Modo Supuestos)
+- S1 ✅ Repository Pattern con DI es obligatorio
+- S2 ✅ Integration tests = BD real, unit tests = mocks
+- S3 ✅ No hay sistema de roles/permisos
+
+### ⚠️ Notas
+- El middleware de auth no cubre rutas /admin/*
+- No hay tests para refresh token
+```
+
+## Integración con Pipeline
+
+```
+/especdev:explorar → hallazgos.md
+→ /especdev:proponer → propuesta de cambio
+→ /especdev:especificar → .feature
+→ ... (pipeline normal)
+```

package/comandos/especdev/guardian.md

@@ -0,0 +1,99 @@
+---
+description: Revisión de código IA como pre-commit hook — Guardian Angel
+i18n: true
+---
+
+# /especdev:guardian
+
+## Objetivo
+
+Ejecutar revisión de código automatizada usando IA como puerta de calidad antes de cada commit. Actúa como un "Ángel Guardián" que valida que el código cumple con los estándares del equipo.
+
+> Inspirado en GGA (Gentleman Guardian Angel) de Gentle-AI.
+
+## Uso
+
+```
+/especdev:guardian                    # Revisar archivos staged
+/especdev:guardian --modo pr          # Revisar todos los cambios del branch vs base
+/especdev:guardian --modo ci          # Para integración continua
+/especdev:guardian --instalar-hook    # Instalar como pre-commit hook
+```
+
+## Cómo Funciona
+
+```
+git add <archivos>
+git commit -m "feat: agregar login"
+    │
+    ├── Hook pre-commit se activa
+    │   └── /especdev:guardian
+    │       ├── Lee archivos staged
+    │       ├── Lee reglas de .especdev/estandares.md
+    │       ├── Envía al LLM para revisión
+    │       └── Resultado:
+    │           ├── ✅ PASS → commit permitido
+    │           ├── ⚠️ WARN → commit con advertencias
+    │           └── ❌ FAIL → commit BLOQUEADO
+    │
+    └── Resultado del commit
+```
+
+## Estandares de Revisión
+
+El archivo `.especdev/estandares.md` define las reglas que el Guardian valida:
+
+```markdown
+# Estándares de Código
+
+## Obligatorios (❌ si falta)
+- [ ] Type hints en todas las firmas de función
+- [ ] No hay `any` / `Any` sin justificación
+- [ ] Tests para lógica de negocio nueva
+- [ ] No credenciales en código fuente
+- [ ] Manejo de errores (no try/catch vacíos)
+
+## Recomendados (⚠️ si falta)
+- [ ] Docstrings en funciones públicas
+- [ ] Nombres descriptivos (no variables de 1 letra)
+- [ ] Imports organizados
+```
+
+## Output
+
+```
+=== Guardian Angel: Revisión de Código ===
+
+Archivos revisados: 3
+Modelo usado: sonnet
+
+✅ PASS: app/services/auth_service.py
+  • Type hints completos
+  • Manejo de errores correcto
+  • Tests existentes
+
+⚠️ WARN: app/routers/auth.py
+  • Falta docstring en endpoint /login (recomendado)
+  • Import no usado: `from typing import Optional`
+
+❌ FAIL: app/config.py
+  • Línea 23: API_KEY hardcodeada — usar variable de entorno
+  • Línea 45: try/except vacío que engulre errores
+
+RESULTADO: BLOQUEADO (1 FAIL)
+→ Corregir los issues marcados con ❌ antes de commitear
+```
+
+## Caché Inteligente
+
+- SHA256 por archivo — solo re-revisa archivos que cambiaron
+- Solo archivos con `PASS` se cachean
+- El caché se invalida si `.especdev/estandares.md` cambia
+
+## Selección de Modelo
+
+| Tipo de Revisión | Modelo |
+|-----------------|--------|
+| Style / lint | `haiku` (rápido, barato) |
+| Lógica de negocio | `sonnet` (balance) |
+| Seguridad / crypto | `opus` (profundidad) |

package/comandos/especdev/historial.md

@@ -0,0 +1,14 @@
+---
+description: Listar sesiones pasadas guardadas en el historial
+i18n: true
+---
+
+# /especdev:historial
+
+## Uso
+
+```
+/especdev:historial
+```
+
+Lista las sesiones almacenadas en `.especdev/historial/`.

package/comandos/especdev/implementar.md

@@ -0,0 +1,227 @@
+---
+description: Ejecutar tareas TDD fase por fase dentro de Docker hasta que todos los tests pasen
+i18n: true
+---
+
+# /especdev:implementar
+
+## Objetivo
+
+Ejecutar las tareas generadas por `/especdev:desglosar` de forma automatizada, siguiendo el ciclo TDD (RED → GREEN → REFACTOR) dentro de un entorno Docker aislado, con checkpoints formalizados para intervención humana.
+
+> Adaptado del comando `speckit.implement` de Specular.
+> Mejorado con Taxonomía de Checkpoints de Get Shit Done (gsd-build/get-shit-done).
+
+## Uso
+
+```
+/especdev:implementar @specs/features/<dominio>/<Feature>.tasks.md
+/especdev:implementar --fase <numero>
+/especdev:implementar --seco   # Solo mostrar plan sin ejecutar
+```
+
+## Comportamiento
+
+1. **Leer** archivo `.tasks.md`
+2. **Verificar** que Docker está disponible
+3. **Verificar Nyquist** — Validar mapeo tests↔requisitos (Puerta 5)
+4. **Ejecutar** tareas fase por fase con checkpoints
+
+### Flujo por Fase
+
+```
+┌─ Fase 1: Setup ───────────────────────────────┐
+│  Crear archivos vacíos: modelos, servicios,    │
+│  repositorios, controladores, tests            │
+│  → Verificar: archivos existen                 │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 2: Tests Unitarios (RED) ───────────────┐
+│  Escribir tests que FALLAN                     │
+│  → docker compose run --rm test                │
+│  → Verificar: tests existen y FALLAN (RED)     │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 3: Tests BDD/Integración (RED) ────────┐
+│  Escribir tests BDD desde Gherkin              │
+│  → Aplicar patrones ISA (isa.yml)             │
+│  → docker compose run --rm test                │
+│  → Verificar: tests BDD existen y FALLAN       │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 4: Lógica de Negocio (GREEN) ──────────┐
+│  Implementar código que hace pasar los tests   │
+│  → docker compose run --rm test                │
+│  → [DETECCIÓN STUBS] automática                │
+│  → Verificar: TODOS los tests PASAN (GREEN)    │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 5: Lint & Tipos ───────────────────────┐
+│  → docker compose run --rm lint                │
+│  → Verificar: sin errores de lint/tipos        │
+└────────────────────────────────────────────────┘
+```
+
+## Taxonomía de Checkpoints
+
+Durante la ejecución, hay momentos donde el agente DEBE pausar para intervención humana. Estos se clasifican en 3 tipos:
+
+### 1. `[checkpoint:verificar]` — Verificación Humana (90% de los casos)
+
+El agente completó una tarea y necesita que el usuario **verifique el resultado** visualmente o funcionalmente.
+
+```markdown
+⏸️ CHECKPOINT: verificar
+Tarea: T013 — Implementar UsuarioController
+Verificación: Abrir http://localhost:3000/register y verificar:
+  - [ ] El formulario renderiza correctamente
+  - [ ] Los campos tienen labels y placeholders
+  - [ ] El submit envía los datos al backend
+  - [ ] Los errores de validación se muestran al usuario
+
+→ ¿Verificado? [sí/no/parcial]
+```
+
+**Cuándo usar:**
+- UI implementada que requiere verificación visual
+- Flujo de usuario completo que requiere testing manual
+- Integración con servicio externo (OAuth, pagos)
+
+### 2. `[checkpoint:decision]` — Decisión Humana (9% de los casos)
+
+El agente llegó a un punto donde hay **múltiples opciones válidas** y necesita una decisión del usuario.
+
+```markdown
+⏸️ CHECKPOINT: decisión
+Tarea: T010 — Implementar UsuarioService
+Decisión requerida: Estrategia de hashing de contraseña
+
+  A) bcrypt (estándar, bien conocido, ~100ms/hash)
+  B) argon2id (más moderno, más seguro, ~200ms/hash)
+  C) scrypt (alternativa, menos popular)
+
+Recomendación: B (argon2id) — mejor resistencia a ataques GPU
+→ Tu elección: [A/B/C]
+```
+
+**Cuándo usar:**
+- Elección de librería/dependencia externa
+- Decisión arquitectónica con trade-offs
+- Configuración de seguridad
+- Proveedor de servicio externo
+
+### 3. `[checkpoint:accion-humana]` — Acción Humana (1% de los casos)
+
+El agente necesita que el usuario **haga algo** que no puede automatizarse.
+
+```markdown
+⏸️ CHECKPOINT: acción-humana
+Tarea: T015 — Configurar OAuth con Google
+Acción requerida: Crear credenciales en Google Cloud Console
+
+  1. Ir a https://console.cloud.google.com/apis/credentials
+  2. Crear OAuth 2.0 Client ID
+  3. Agregar redirect URI: http://localhost:3000/api/auth/callback/google
+  4. Copiar Client ID y Client Secret
+
+→ Proporcionar:
+  - GOOGLE_CLIENT_ID: ___
+  - GOOGLE_CLIENT_SECRET: ___
+```
+
+**Cuándo usar:**
+- Configuración de servicios externos (OAuth, DNS, certificados)
+- Acciones en dashboards que no tienen API/CLI
+- Aprobaciones organizacionales
+- Configuración de hardware/dispositivos
+
+### Principio: "Si el agente puede ejecutarlo, el agente lo ejecuta"
+
+Los checkpoints son **excepciones**, no la norma. Solo usar cuando genuinamente se necesita intervención humana.
+
+| Automatizable | NO checkpoint | Ejemplo |
+|---------------|---------------|---------|
+| Instalar dependencia | `npm install bcrypt` | El agente lo ejecuta |
+| Crear migración | `prisma migrate dev` | El agente lo ejecuta |
+| Ejecutar tests | `pytest` | El agente lo ejecuta |
+| Formatear código | `prettier --write .` | El agente lo ejecuta |
+
+| No automatizable | SÍ checkpoint | Tipo |
+|------------------|---------------|------|
+| ¿Se ve bien la UI? | Verificar | `verificar` |
+| ¿bcrypt o argon2? | Decidir | `decisión` |
+| Crear API key en dashboard | Acción | `acción-humana` |
+
+## Regla Stop-Loss
+
+> Si una tarea falla (luz ROJA) más de **3 veces** durante la implementación, el trabajo DEBE detenerse y se DEBE solicitar guía humana. Los ciclos infinitos de fix-break están **PROHIBIDOS**.
+
+Integración con **Detección de Loops** (habilidad): si se detecta un loop, escalar según los 3 niveles de escape antes de llegar al stop-loss.
+
+## Ejemplo
+
+```bash
+/especdev:implementar @specs/features/usuario/CrearUsuario.tasks.md
+
+=== Implementando: CrearUsuario ===
+
+📁 Fase 1: Setup
+  ✅ app/models/usuario.py (creado)
+  ✅ app/services/usuario_service.py (creado)
+  ✅ tests/unit/test_usuario_service.py (creado)
+  ✅ tests/integracion/test_crear_usuario.py (creado)
+
+🔴 Fase 2: Tests Unitarios (RED)
+  ✅ 3 tests escritos
+  ✅ 3/3 FALLAN (RED esperado)
+
+🔴 Fase 3: Tests BDD (RED)
+  ✅ 4 escenarios BDD escritos (desde .feature)
+  ✅ 4/4 FALLAN (RED esperado)
+  ✅ ISA patterns aplicados
+
+⏸️ CHECKPOINT: decisión
+  Estrategia de hashing: bcrypt vs argon2id
+  → Usuario elige: argon2id
+
+🟢 Fase 4: Lógica de Negocio (GREEN)
+  ✅ UsuarioService.crear() implementado
+  ✅ Detección de stubs: 0 stubs encontrados
+  ✅ 7/7 tests PASAN (GREEN)
+
+⏸️ CHECKPOINT: verificar
+  Abrir http://localhost:3000/register
+  → Usuario verifica: ✅ OK
+
+✨ Fase 5: Lint
+  ✅ Sin errores de lint
+  ✅ 0 type errors
+
+=== COMPLETO ===
+Todos los tests pasan. Feature implementada exitosamente.
+```
+
+## Integración con Docker
+
+```yaml
+# docker-compose.yml (requerido)
+services:
+  test:
+    build: .
+    command: pytest -v
+    volumes:
+      - .:/app
+  lint:
+    build: .
+    command: |
+      flake8 app/ &&
+      mypy app/ --strict
+    volumes:
+      - .:/app
+  reporte:
+    build: .
+    command: pytest --html=reports/test-report.html --self-contained-html
+    volumes:
+      - .:/app
+      - ./reports:/app/reports
+```