don-cheli-sdd 1.13.0

package/habilidades/deteccion-loops/HABILIDAD.md

@@ -0,0 +1,168 @@
+---
+nombre: Detección de Loops
+descripcion: "Detectar ciclos infinitos en la ejecución del agente (A→B→A→B) y escalar antes del stop-loss"
+version: 1.0.0
+autor: Don Cheli
+tags: [calidad, loops, ciclos, detección, auto-corrección]
+activacion: "loop detectado", "ciclo infinito", "estoy en un loop", "stuck"
+---
+
+# Habilidad: Detección de Loops en Auto-Corrección
+
+**Versión:** 1.0.0
+**Categoría:** Calidad
+**Tipo:** Rígida
+
+> Adaptado de DeepCode (HKUDS/DeepCode) — Loop Detection & Error Correction.
+
+## Cómo Mejora el Framework
+
+Don Cheli ya tiene auto-corrección (aprendizajes acumulados), pero carece de un **guard contra ciclos infinitos de fix**. Cuando el agente intenta corregir un error y la corrección genera otro error similar, puede entrar en un loop destructivo que consume tokens sin avanzar.
+
+Esta habilidad detecta y rompe esos ciclos automáticamente.
+
+## El Problema
+
+```
+Intento 1: Fix A → genera Error B
+Intento 2: Fix B → genera Error A (¡loop!)
+Intento 3: Fix A → genera Error B
+... (infinito, consumiendo tokens)
+```
+
+## Mecanismo de Detección
+
+### 1. Registro de Intentos
+
+Cada corrección se registra con su firma:
+
+```
+[INTENTO] #N | Error: <firma> | Archivo: <ruta> | Fix: <descripción>
+```
+
+La **firma del error** es un hash del tipo + mensaje + ubicación:
+
+```
+firma = hash(tipo_error + mensaje_normalizado + archivo + línea)
+```
+
+### 2. Detección de Patrones
+
+El sistema detecta loops cuando:
+
+| Patrón | Condición | Ejemplo |
+|--------|-----------|---------|
+| **Loop directo** | Misma firma aparece 2+ veces | Error A → Fix → Error A |
+| **Loop ping-pong** | Dos firmas alternan | Error A → Error B → Error A |
+| **Loop espiral** | 3+ firmas en ciclo | A → B → C → A |
+| **Estancamiento** | 3+ intentos sin progreso medible | Fix no cambia resultado de tests |
+
+### 3. Umbrales
+
+| Umbral | Valor | Acción |
+|--------|-------|--------|
+| **Max intentos por error** | 3 | Escalar después del 3er intento |
+| **Max intentos totales por tarea** | 8 | Stop-loss de la tarea |
+| **Ventana de detección** | Últimos 10 intentos | Firmas se comparan en ventana deslizante |
+| **Timeout por intento** | 60 segundos | Prevenir fixes que cuelgan |
+
+## Flujo de Corrección con Guard
+
+```
+1. Detectar error
+2. ¿Firma ya vista en ventana?
+   ├── NO → Intentar fix, registrar intento
+   │   └── ¿Fix exitoso?
+   │       ├── SÍ → Limpiar registro, continuar
+   │       └── NO → Volver a paso 2
+   │
+   └── SÍ → ¿Cuántas veces?
+       ├── 2 veces → Cambiar estrategia de fix
+       ├── 3 veces → ⛔ PARAR, reportar al usuario
+       └── Escalar con contexto completo
+```
+
+## Estrategias de Escape
+
+Cuando se detecta un loop, antes de escalar al usuario se intentan **estrategias alternativas** (en orden):
+
+### Nivel 1: Cambiar Estrategia (automático)
+```
+1. Si el fix fue en el mismo archivo → intentar fix en archivo diferente
+2. Si el fix fue sintáctico → intentar fix semántico
+3. Si el fix fue local → intentar fix en dependencia
+```
+
+### Nivel 2: Ampliar Contexto (automático)
+```
+1. Leer archivos adyacentes (imports, dependencias)
+2. Revisar tests para entender comportamiento esperado
+3. Consultar historial git del archivo
+```
+
+### Nivel 3: Escalar al Usuario (manual)
+```
+⛔ LOOP DETECTADO
+
+Error: TypeError: Cannot read property 'id' of undefined
+Archivo: src/services/auth.ts:42
+Intentos: 3
+Estrategias probadas:
+  1. Agregar null check → generó error en caller
+  2. Inicializar objeto vacío → falló validación
+  3. Agregar default parameter → TypeScript error
+
+Contexto del loop:
+  - El objeto `user` llega como undefined desde `getSession()`
+  - `getSession()` devuelve undefined cuando el token expira
+  - El fix necesita decisión de negocio: ¿redirigir al login o renovar token?
+
+Opciones sugeridas:
+  A) Redirigir al login cuando el token expira
+  B) Implementar refresh token automático
+  C) Otro enfoque: [tu input]
+```
+
+## Integración con Auto-Corrección Existente
+
+Esta habilidad **extiende** la auto-corrección existente, no la reemplaza:
+
+```
+Auto-Corrección (aprendizajes)     Detección de Loops (guard)
+├── Registra correcciones           ├── Registra intentos de fix
+├── Acumula reglas                  ├── Detecta ciclos
+├── Previene errores futuros        ├── Previene loops presentes
+└── Propone al usuario              └── Escala al usuario
+```
+
+## Registro en Memoria
+
+Cuando un loop se resuelve, se registra en `.especdev/memoria/loops-resueltos.md`:
+
+```markdown
+## Loop Resuelto: 2026-03-21
+
+- **Error:** TypeError en auth.ts:42
+- **Causa raíz:** Token expirado no manejado
+- **Intentos antes de resolución:** 3
+- **Estrategia exitosa:** Nivel 3 (decisión del usuario: refresh token)
+- **Regla aprendida:** Siempre manejar caso de token expirado en servicios auth
+```
+
+## Métricas
+
+El sistema trackea:
+
+| Métrica | Propósito |
+|---------|-----------|
+| Loops detectados por sesión | Medir frecuencia |
+| Intentos promedio antes de detección | Medir eficiencia |
+| Estrategia de escape más efectiva | Optimizar respuesta |
+| Tokens ahorrados vs sin detección | Justificar la habilidad |
+
+## Guardrails
+
+- **Nunca** silenciar un loop — siempre informar
+- **Nunca** superar el stop-loss (8 intentos) sin escalar
+- **Siempre** registrar el loop resuelto para aprendizaje futuro
+- **Siempre** proponer opciones al usuario, no decidir en loops de Nivel 3

package/habilidades/deteccion-stubs/HABILIDAD.md

@@ -0,0 +1,204 @@
+---
+nombre: Detección de Stubs
+descripcion: "Detectar código stub (TODO, placeholder, mock sin implementar) antes de marcar una tarea como completa"
+version: 1.0.0
+autor: Don Cheli
+tags: [calidad, stubs, TODOs, placeholders, completitud]
+activacion: "detectar stubs", "buscar TODOs", "código incompleto", "placeholders"
+---
+
+# Habilidad: Detección de Stubs (Código Placeholder)
+
+**Versión:** 1.0.0
+**Categoría:** Calidad
+**Tipo:** Rígida
+
+> Adaptado de Get Shit Done (gsd-build/get-shit-done) — Stub Detection Patterns.
+
+## Cómo Mejora el Framework
+
+Un problema frecuente del desarrollo asistido por IA: el agente genera código placeholder (stubs) y lo reporta como "implementado". Don Cheli tiene revisión de código, pero no un sistema específico para detectar stubs que pasan como código completo.
+
+## El Problema
+
+```
+Agente: "✅ Implementé el servicio de pagos"
+Código real:
+  async processPayment(data) {
+    // TODO: implement payment processing
+    return { success: true };
+  }
+```
+
+El agente "completó" la tarea, pero el código es un stub.
+
+## Patrones de Detección
+
+### Indicadores Universales
+
+| Patrón | Ejemplo | Severidad |
+|--------|---------|-----------|
+| **TODO/FIXME/HACK** | `// TODO: implement this` | ❌ Crítico |
+| **Return vacío o hardcoded** | `return {};`, `return true;`, `return []` | ❌ Crítico |
+| **Throw no implementado** | `throw new Error('Not implemented')` | ❌ Crítico |
+| **Console.log como lógica** | `console.log('called')` sin más lógica | ⚠️ Alto |
+| **Valores hardcoded** | `return 42;`, `return "test"` | ⚠️ Alto |
+| **Lorem ipsum** | `"Lorem ipsum dolor sit amet"` | ⚠️ Alto |
+| **Pass/noop** | `pass` (Python), `{}` (cuerpo vacío) | ⚠️ Alto |
+| **Placeholder de config** | `"your-api-key-here"`, `"xxx"`, `"changeme"` | ❌ Crítico |
+
+### Patrones por Tipo de Artefacto
+
+#### React/Frontend
+```
+❌ Componente que solo renderiza <div>placeholder</div>
+❌ Handler onClick vacío: onClick={() => {}}
+❌ Estilos inline con valores mágicos sin design token
+❌ Imágenes placeholder sin src real
+⚠️ Componente sin props tipados (any)
+```
+
+#### API/Backend
+```
+❌ Endpoint que retorna data mockeada/hardcoded
+❌ Middleware que no hace nada (next() directo)
+❌ Validación que acepta todo (return true)
+❌ Error handler que traga excepciones silenciosamente
+⚠️ Service con un solo método implementado de N declarados
+```
+
+#### Base de Datos
+```
+❌ Migración vacía (up/down sin operaciones)
+❌ Seed con datos obviamente falsos ("test@test.com", "John Doe")
+❌ Query que retorna SELECT * sin filtro ni paginación
+⚠️ Índices declarados pero sin justificación de uso
+```
+
+#### Tests
+```
+❌ Test que siempre pasa: expect(true).toBe(true)
+❌ Test sin assertions
+❌ Test que solo verifica que no lanza error (sin verificar output)
+⚠️ Test con un solo caso (falta edge cases)
+```
+
+### Verificación de Cableado (Wiring)
+
+Detectar que los componentes están realmente conectados:
+
+| Conexión | Verificación |
+|----------|-------------|
+| **Componente → API** | Componente hace fetch/call real, no datos hardcoded |
+| **API → Base de Datos** | Endpoint ejecuta query real, no retorna mock |
+| **Form → Handler** | Submit ejecuta lógica, no solo console.log |
+| **Error → UI** | Errores se muestran al usuario, no solo se loggean |
+
+## Cuándo Ejecutar
+
+| Momento | Trigger |
+|---------|---------|
+| **Post-implementación** | Después de cada tarea GREEN en `/especdev:implementar` |
+| **Pre-revisión** | Antes de `/especdev:revisar` |
+| **Pre-merge** | Como parte de la Puerta 6 (Merge de Código) |
+
+## Flujo de Detección
+
+```
+1. Escanear archivos modificados/creados
+2. Aplicar patrones universales
+3. Aplicar patrones por tipo de artefacto
+4. Verificar cableado entre capas
+5. Generar reporte
+
+¿Stubs encontrados?
+├── SÍ → ⛔ BLOQUEAR tarea como incompleta
+│   └── Listar cada stub con ubicación y severidad
+└── NO → ✅ Tarea genuinamente completa
+```
+
+## Reporte de Stubs
+
+```markdown
+## Detección de Stubs: CrearUsuario
+
+Archivos escaneados: 8
+Stubs detectados: 3
+
+### ❌ Crítico
+
+1. **src/services/email_service.py:15**
+   Patrón: Return hardcoded
+   ```python
+   async def send_welcome_email(user):
+       return True  # No envía email real
+   ```
+   Acción: Implementar envío con servicio de email
+
+2. **src/controllers/usuario_controller.py:42**
+   Patrón: TODO pendiente
+   ```python
+   # TODO: add rate limiting
+   ```
+   Acción: Implementar rate limiting o remover TODO si no aplica
+
+### ⚠️ Alto
+
+3. **tests/unit/test_email.py:8**
+   Patrón: Test sin assertion real
+   ```python
+   def test_send_email():
+       result = send_welcome_email(mock_user)
+       assert result is not None  # No verifica comportamiento
+   ```
+   Acción: Verificar que el servicio de email fue llamado con los parámetros correctos
+
+### Resultado: ❌ NO-AVANZAR (2 críticos, 1 alto)
+```
+
+## Integración con Pipeline
+
+```
+/especdev:implementar (cada tarea GREEN)
+  → [DETECCIÓN STUBS] ← automática
+  → ¿Stubs encontrados?
+     ├── SÍ → Tarea regresa a RED (implementar de verdad)
+     └── NO → Tarea completa, siguiente tarea
+
+/especdev:revisar
+  → [DETECCIÓN STUBS] ← segunda pasada
+  → Reporte incluido en review
+```
+
+## Integración con Puertas de Calidad
+
+Se integra como verificación en la **Puerta 6** (Merge de Código):
+
+```
+Puerta 6: Merge de Código
+├── Tests verdes ✅
+├── Lint limpio ✅
+├── Type-check pasa ✅
+├── Coverage ≥ 85% ✅
+├── Sin diff no relacionado ✅
+└── Sin stubs detectados ✅ ← NUEVA
+```
+
+## Excepciones
+
+Hay casos legítimos donde un "stub" es intencional:
+
+| Caso | Cómo marcar | Ejemplo |
+|------|------------|---------|
+| Feature flag deshabilitado | `// STUB:feature-flag:nombre-flag` | Funcionalidad para release futuro |
+| Mock en test | No aplica (stubs en tests de mock son válidos) | `jest.fn()` |
+| Interface/abstract | No aplica (declaraciones sin cuerpo son válidas) | `abstract class` |
+
+Usar el comentario `// STUB:razón` para excluir de detección.
+
+## Guardrails
+
+- **Nunca** marcar una tarea como completa si tiene stubs críticos
+- **Nunca** ignorar stubs silenciosamente — siempre reportar
+- **Siempre** verificar cableado entre capas (no solo código individual)
+- **Siempre** respetar excepciones marcadas con `// STUB:razón`

package/habilidades/devlog/HABILIDAD.md

@@ -0,0 +1,84 @@
+---
+nombre: DevLog — Bitácora de Desarrollo
+descripcion: "Mantener un log de desarrollo con decisiones, cambios y contexto para referencia futura"
+version: 1.0.0
+autor: Don Cheli
+tags: [devlog, bitacora, historial, observabilidad]
+activacion: "devlog", "registrar decisión", "log de desarrollo"
+---
+
+# Habilidad: DevLog — Bitácora de Desarrollo
+
+**Versión:** 1.0.0
+**Categoría:** Observabilidad
+**Tipo:** Flexible
+
+> Adaptado de DevilDev — DevLog para historial de desarrollo.
+
+## Cómo Mejora el Framework
+
+El DevLog es una bitácora cronológica de TODOS los cambios significativos del proyecto. Complementa la memoria persistente con un registro temporal ordenado.
+
+## Diferencia con Memoria Persistente
+
+| Memoria Persistente | DevLog |
+|--------------------|--------|
+| Decisiones y convenciones | Historial cronológico |
+| "QUÉ decidimos" | "QUÉ pasó y CUÁNDO" |
+| Se actualiza (sobrescribe) | Solo se agrega (append) |
+| Para contexto | Para auditoría |
+
+## Formato
+
+```markdown
+# DevLog: mi-proyecto
+
+## 2026-03-21
+
+### 16:30 — Feature: OAuth Login (PROJ-42)
+- **Tipo:** Feature
+- **Archivos:** 8 modificados, +234 -45 líneas
+- **Arquitectura:** Nuevo componente "OAuth Provider"
+- **Spec:** auth-oauth.delta.md
+- **Tests:** 12 nuevos (todos pasan)
+- **Tokens:** 58,120 | Costo: $0.14
+- **Notas:** Se eligió Strategy Pattern para extensibilidad
+
+### 14:15 — Fix: Login timeout (PROJ-41)
+- **Tipo:** Bugfix
+- **Archivos:** 2 modificados, +8 -4 líneas
+- **Tests:** 1 nuevo (regression test)
+- **Tokens:** 12,500 | Costo: $0.03
+- **Notas:** Timeout aumentado de 30s a 60s
+
+## 2026-03-20
+
+### 11:00 — Refactor: Separar servicio de email
+- **Tipo:** Refactor
+- **Archivos:** 5 modificados, +120 -180 líneas
+- **Arquitectura:** Componente "Email Service" extraído de "API"
+- **Tests:** Sin cambios (todos siguen pasando)
+```
+
+## Auto-Registro
+
+El DevLog se actualiza automáticamente cuando:
+1. `/especdev:archivar` completa un cambio
+2. `/especdev:aplicar` termina una implementación
+3. Se crea un commit significativo
+
+## Ubicación
+
+```
+.especdev/devlog/
+├── 2026-03.md    # Log del mes
+├── 2026-02.md    # Mes anterior
+└── indice.md     # Índice con conteos por mes
+```
+
+## Valor para el Equipo
+
+- **Onboarding:** "¿Qué pasó este mes?" → DevLog
+- **Retrospectivas:** Datos reales de qué se hizo
+- **Debugging:** "¿Cuándo se cambió esto?" → Buscar en DevLog
+- **Estimados:** Datos históricos de duración y costo por tipo de cambio

package/habilidades/documentacion-viva/HABILIDAD.md

@@ -0,0 +1,231 @@
+---
+nombre: Documentación Viva
+descripcion: "Generar y mantener documentación sincronizada con el código: ADRs, OpenAPI, diagramas Mermaid"
+version: 1.0.0
+autor: Don Cheli
+tags: [documentación, ADR, OpenAPI, Mermaid, diagramas]
+activacion: "documentación viva", "generar docs", "ADR", "OpenAPI", "diagrama"
+---
+
+# Habilidad: Documentación Técnica Viva
+
+**Versión:** 1.0.0
+**Categoría:** Documentación
+**Tipo:** Flexible
+
+## Cómo Mejora el Framework
+
+Don Cheli tiene devlog (registro cronológico) y trazabilidad (pipeline de artefactos), pero carece de un sistema para generar y mantener documentación técnica **que evoluciona con el código**: ADRs, specs OpenAPI, y documentación de decisiones.
+
+## Tipos de Documentación
+
+### 1. ADRs — Architecture Decision Records
+
+Documentan el **por qué** detrás de decisiones técnicas.
+
+```markdown
+# ADR-001: Usar PostgreSQL en vez de MongoDB
+
+**Estado:** Aceptado
+**Fecha:** 2026-03-21
+**Contexto:** Necesitamos una base de datos para el sistema de pedidos.
+**Decisión:** Usar PostgreSQL 16.
+**Consecuencias:**
+  - (+) Transacciones ACID para pedidos
+  - (+) JSON support para datos semi-estructurados
+  - (-) Requiere schema upfront (menos flexible que Mongo)
+  - (-) Más configuración inicial
+
+**Alternativas evaluadas:**
+  - MongoDB: descartada por falta de transacciones multi-documento nativas
+  - SQLite: descartada por límites de concurrencia (ver PoC poc/sqlite-mvp/)
+```
+
+**Ubicación:** `.especdev/memoria/decisiones/ADR-###.md`
+
+**Cuándo crear:**
+- Elección de tecnología/librería
+- Decisión arquitectónica (monolito vs micro, REST vs GraphQL)
+- Trade-off significativo con alternativas válidas
+- Checkpoint tipo `decisión` en `/especdev:implementar`
+
+**Cuándo NO crear:**
+- Decisiones obvias sin alternativas reales
+- Elecciones de estilo/formato
+- Configuraciones menores
+
+### 2. Specs OpenAPI / Swagger
+
+Generación automática de especificaciones de API desde los contratos del plan.
+
+**Trigger:** Después de `/especdev:planificar-tecnico` si el plan incluye contratos API.
+
+```yaml
+# specs/api/openapi.yaml (auto-generado)
+openapi: 3.1.0
+info:
+  title: Mi Proyecto API
+  version: 1.0.0
+
+paths:
+  /api/v1/usuarios:
+    post:
+      summary: Crear usuario
+      operationId: crearUsuario
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CrearUsuarioRequest'
+      responses:
+        '201':
+          description: Usuario creado
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/UsuarioResponse'
+        '400':
+          description: Datos inválidos
+        '409':
+          description: Email duplicado
+
+components:
+  schemas:
+    CrearUsuarioRequest:
+      type: object
+      required: [email, password, nombre]
+      properties:
+        email:
+          type: string
+          format: email
+        password:
+          type: string
+          minLength: 8
+        nombre:
+          type: string
+          maxLength: 100
+    UsuarioResponse:
+      type: object
+      properties:
+        id:
+          type: string
+          format: uuid
+        email:
+          type: string
+        nombre:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+```
+
+**Ubicación:** `specs/api/openapi.yaml`
+
+**Auto-actualización:** Cuando `/especdev:planificar-tecnico` genera un nuevo contrato API, el OpenAPI spec se actualiza automáticamente.
+
+### 3. Docstrings/JSDoc Significativos
+
+Guía para generar comentarios que aportan valor (no ruido).
+
+```
+✅ Documentar:
+  - WHY (por qué existe esta función/clase)
+  - Parámetros con tipos y restricciones
+  - Excepciones que puede lanzar
+  - Efectos secundarios (escribe en BD, envía email)
+  - Invariantes y precondiciones
+
+❌ NO documentar:
+  - WHAT (qué hace — si el nombre no lo dice, renombrar)
+  - Código obvio (// incrementar contador → i++)
+  - Getters/setters triviales
+  - Re-describir los tipos que ya son explícitos
+```
+
+**Ejemplo bueno:**
+```python
+def process_refund(payment_id: str, amount: Decimal | None = None) -> RefundResult:
+    """Procesa reembolso total o parcial via Stripe.
+
+    Si amount es None, reembolsa el total. Reembolsos parciales
+    acumulativos no pueden exceder el monto original.
+
+    Raises:
+        PaymentNotFoundError: payment_id no existe
+        RefundExceedsPaymentError: monto acumulado > original
+        StripeError: error de comunicación con Stripe (auto-retry 3x)
+
+    Side effects:
+        - Crea registro en tabla refunds
+        - Envía email de confirmación al usuario (async)
+    """
+```
+
+### 4. Diagramas como Código
+
+Usar Mermaid para diagramas que viven con el código:
+
+```markdown
+## Flujo de Autenticación
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant A as API
+    participant S as AuthService
+    participant D as Database
+
+    U->>A: POST /login {email, password}
+    A->>S: authenticate(email, password)
+    S->>D: findByEmail(email)
+    D-->>S: User | null
+    alt Usuario existe
+        S->>S: verifyPassword(password, hash)
+        S-->>A: JWT token
+        A-->>U: 200 {token}
+    else No existe
+        S-->>A: throw UnauthorizedError
+        A-->>U: 401 {error}
+    end
+```
+```
+
+**Ubicación:** Inline en specs, plans, o ADRs.
+
+## Ciclo de Vida de la Documentación
+
+```
+Código cambia → ¿Docs afectadas?
+├── API cambió → Actualizar OpenAPI
+├── Decisión arquitectónica → Crear/actualizar ADR
+├── Nuevo módulo → Actualizar mapa arquitectónico
+├── Nuevo flujo → Agregar diagrama Mermaid
+└── Solo lógica interna → No requiere docs
+```
+
+## Verificación de Frescura
+
+| Documento | Frecuencia de verificación | Cómo verificar |
+|-----------|---------------------------|----------------|
+| OpenAPI | Cada PR con cambio de API | Diff entre spec y código |
+| ADRs | Cada fase de Estrategia | ¿Decisiones siguen vigentes? |
+| Diagramas | Cada cambio arquitectónico | ¿Flujo coincide con código? |
+| README | Cada release | ¿Instrucciones funcionan? |
+
+## Integración con Pipeline
+
+```
+/especdev:planificar-tecnico → genera OpenAPI si hay API
+/especdev:implementar (checkpoint:decisión) → genera ADR
+/especdev:revisar → verifica frescura de docs
+/especdev:archivar → snapshot de docs con versión
+```
+
+## Guardrails
+
+- **Nunca** duplicar información entre docs — referenciar con links
+- **Nunca** documentar código obvio (renombrar en vez de comentar)
+- **Siempre** crear ADR para decisiones con alternativas válidas
+- **Siempre** actualizar OpenAPI cuando cambia un contrato de API
+- **Máximo** ~200 líneas por documento (constitución Art. de concisión)