don-cheli-sdd 1.13.0

package/habilidades/planning-equipo/HABILIDAD.md

@@ -0,0 +1,169 @@
+---
+nombre: Planning de Equipo Semanal
+descripcion: "Facilitar plannings semanales: revisión de RFCs, priorización WSJF, asignación por responsable/pareja/squad, seguimiento de avance"
+version: 1.0.0
+autor: Don Cheli
+tags: [planning, sprint, rfcs, priorización, equipo, asignación, WSJF, parejas, squads]
+activacion: "planning semanal", "planificar sprint", "revisar RFCs", "asignar tareas", "priorizar backlog"
+---
+
+# Habilidad: Planning de Equipo Semanal
+
+**Versión:** 1.0.0
+**Categoría:** Gestión de Equipo
+**Tipo:** Interactivo
+
+## Propósito
+
+Orquestar el planning semanal de un equipo de desarrollo de forma estructurada: desde la revisión de RFCs hasta la asignación de tareas con compromisos medibles.
+
+## Capacidades
+
+### 1. Cálculo de capacidad del equipo
+Calcula la capacidad efectiva considerando:
+- Días disponibles por persona (vacaciones, feriados, soporte)
+- Factor de foco (meetings, interrupciones, on-call)
+- Carry-over de la semana anterior
+
+**Fórmula:**
+```
+Capacidad efectiva = Σ(días_disponibles_i) × factor_foco
+```
+
+Factores de foco recomendados:
+| Tipo de equipo | Factor |
+|----------------|--------|
+| Pocas reuniones, sin on-call | 0.8 |
+| Promedio | 0.7 |
+| Mucho soporte/on-call | 0.5-0.6 |
+
+### 2. Evaluación de RFCs
+Cada RFC se evalúa en 5 dimensiones (1-5):
+
+| Dimensión | Peso |
+|-----------|------|
+| Impacto de negocio | 1.5x |
+| Urgencia | 1.3x |
+| Reducción de riesgo/deuda | 1.0x |
+| Riesgo técnico (inverso) | 0.8x |
+| Tamaño (inverso) | 0.7x |
+
+**Score compuesto:** `(impacto×1.5 + urgencia×1.3 + riesgo×1.0) / (tamaño×0.7 + riesgo_tecnico×0.8)`
+
+### 3. Priorización WSJF
+Weighted Shortest Job First: maximizar valor entregado por unidad de tiempo.
+
+```
+WSJF = (Valor_negocio + Time_criticality + Risk_reduction) / Job_size
+```
+
+Orden de ejecución:
+1. **Bugs en producción** (siempre primero, sin WSJF)
+2. **Carry-over** (completar WIP antes de empezar nuevo)
+3. **WSJF descendente** (mayor score primero)
+
+### 4. Asignación inteligente
+Tres modalidades de asignación:
+
+#### Individual
+- Tareas bien definidas con un solo dominio
+- Persona con expertise y disponibilidad
+- Máximo 2 items activos por persona (regla WIP)
+
+#### Pareja (Pair Programming)
+- Tareas que cruzan dominios (backend + frontend)
+- Mentoring: senior + junior obligatorio
+- Conocimiento crítico que debe distribuirse (reducir bus factor)
+- **Rotación:** las parejas DEBEN cambiar cada semana
+
+#### Squad (3+ personas)
+- Iniciativas que necesitan diseño + implementación + integración
+- Lead designado + daily sync propio
+- Timebox: máximo 1 semana, luego evaluar
+
+### 5. Gestión de RFCs
+
+#### Estados de un RFC
+```
+Draft → En revisión → Aprobado → En progreso → Completado
+                    ↘ Rechazado
+                    ↘ Postergado (con fecha de revisión)
+```
+
+#### Plantilla de RFC
+```markdown
+# RFC-XXX: Título
+
+**Autor:** Nombre | **Fecha:** YYYY-MM-DD | **Estado:** Draft
+**Reviewers:** Persona1, Persona2
+
+## Problema
+Qué problema resuelve y por qué es importante ahora.
+
+## Propuesta
+Solución propuesta con suficiente detalle para estimar.
+
+## Alternativas consideradas
+Al menos 1 alternativa y por qué fue descartada.
+
+## Impacto
+- Usuarios afectados: X
+- Sistemas afectados: Y
+- Riesgo de no hacerlo: Z
+
+## Estimado preliminar
+- Tamaño: S/M/L/XL
+- Personas necesarias: N
+- Dependencias: lista
+
+## Decisión
+(se completa después de la revisión en planning)
+```
+
+### 6. Seguimiento mid-week
+Comparar plan vs realidad:
+- Items completados vs comprometidos
+- Capacidad utilizada vs planificada
+- Bloqueos detectados
+- Ajustes necesarios para el resto de la semana
+
+### 7. Retrospectiva de planning
+Después de 4 plannings acumulados, generar patrones:
+- Precisión de estimaciones (estimado vs real)
+- Items que se arrastran recurrentemente
+- Distribución de carga por persona
+- Parejas que mejor funcionan
+- RFCs que se postergan sin razón clara
+
+## Reglas de la habilidad
+
+### No negociables
+1. **Nunca 100% de capacidad** — siempre aplicar factor de foco
+2. **WIP limit: 2** — nadie tiene más de 2 tareas activas
+3. **Juniors en pareja** — siempre con un senior
+4. **Carry-over de 3 semanas → decisión** — replantear, escalar, o cancelar
+5. **Parejas rotan** — ningún par se repite 2 semanas seguidas
+
+### Heurísticas
+- Si un RFC no tiene reviewers asignados, no puede entrar al planning
+- Si la capacidad < 50%, priorizar solo bugs y carry-over
+- Si hay más de 3 items en carry-over, dedicar la primera mitad de la semana solo a cerrar WIP
+- Si un RFC tiene score WSJF > 8 y tamaño > L, dividirlo antes de asignar
+
+## Archivos generados
+
+| Archivo | Contenido |
+|---------|-----------|
+| `.especdev/plannings/YYYY-WNN.md` | Planning semanal completo |
+| `.especdev/plannings/_retrospectiva.md` | Patrones entre plannings |
+| `.especdev/rfcs/RFC-XXX.md` | RFC individual |
+| `.especdev/rfcs/_indice.md` | Índice de RFCs con estado |
+
+## Integración
+
+| Habilidad | Uso |
+|-----------|-----|
+| `estimacion` | Estimar RFCs antes del planning |
+| `reflexion` | Retrospectiva post-sprint |
+| `trazabilidad` | Vincular RFCs con PRs y specs |
+| `orquestacion-autonoma` | Ejecutar tareas asignadas en bucle |

package/habilidades/presentaciones/HABILIDAD.md

@@ -0,0 +1,63 @@
+---
+nombre: Presentaciones Interactivas (HTML Slides)
+descripcion: "Generar presentaciones interactivas HTML autocontenidas desde contenido del proyecto"
+version: 1.0.0
+autor: Don Cheli
+tags: [presentaciones, html, slides, documentacion]
+activacion: "presentación", "slides", "presentar proyecto", "generar HTML"
+---
+
+# Habilidad: Presentaciones Interactivas (HTML Slides)
+
+**Versión:** 1.0.0
+**Categoría:** Documentación
+**Tipo:** Flexible
+
+> Adaptado de frontend-slides (zarazhangrui/frontend-slides) — Generación de presentaciones HTML sin dependencias.
+
+## Cómo Mejora el Framework
+
+Permite generar presentaciones interactivas de proyectos, demos, pitches y documentación técnica como archivos HTML autocontenidos — sin PowerPoint, sin Figma, sin dependencias externas.
+
+## Uso
+
+```
+/especdev:presentar <tema o archivo>
+/especdev:presentar --tema "bold-signal"     # Elegir tema visual
+/especdev:presentar --desde pptx input.pptx  # Convertir desde PowerPoint
+```
+
+## Tecnología
+
+- HTML5/CSS3/JavaScript puro (sin frameworks)
+- Un solo archivo `.html` autocontenido
+- Navegación por teclado, mouse y touch
+- Animaciones con Intersection Observer
+- Responsive con `clamp()` para todos los tamaños
+- 12 temas de diseño disponibles
+
+## Temas Disponibles
+
+| Tema | Estilo | Ideal para |
+|------|--------|-----------|
+| **bold-signal** | Dark, alto contraste, acentos vibrantes | Demos técnicas |
+| **electric-studio** | Dark, profesional, minimalista | Pitches |
+| **neon-cyber** | Dark, futurista, cyan/magenta | Devtools |
+| **terminal-green** | Dark, hacker, monospace | Conferencias dev |
+| **notebook-tabs** | Light, editorial, tabs de color | Workshops |
+| **pastel-geometry** | Light, amigable, redondeado | Onboarding |
+| **swiss-modern** | Bauhaus, geométrico, precisión | Arquitectura |
+
+## Output
+
+Archivo HTML autocontenido con:
+- Slides de 100vh (una pantalla por slide)
+- Navegación: flechas, espacio, scroll, swipe
+- Barra de progreso
+- Animaciones de entrada
+
+## Guardrails
+
+- Cada slide debe caber en 100vh (sin scroll interno)
+- Imágenes con max-height relativo al viewport
+- Máximo ~15 slides para mantener engagement

package/habilidades/proyecciones-costo/HABILIDAD.md

@@ -0,0 +1,54 @@
+---
+nombre: Proyecciones de Costo
+descripcion: Estimar costo restante basándose en consumo real de tokens y slices completados
+version: 1.0.0
+autor: Don Cheli
+tags: [costos, estimacion, tokens, observabilidad]
+---
+
+# Proyecciones de Costo
+
+## Propósito
+
+Después de completar 2+ slices o tareas, proyectar el costo total del proyecto basándose en el consumo real observado.
+
+## Fórmula
+
+```
+costo_promedio_por_slice = tokens_consumidos_total / slices_completados
+costo_restante_estimado = costo_promedio_por_slice × slices_pendientes
+costo_total_proyectado = tokens_consumidos_total + costo_restante_estimado
+```
+
+## Factores de Ajuste
+
+| Factor | Multiplicador | Cuándo |
+|--------|---------------|--------|
+| Slices iniciales (setup) | 0.7× | Los primeros 2 slices suelen ser más caros (setup) |
+| Slices finales (polish) | 0.5× | Los últimos slices suelen ser más baratos |
+| Re-work por review | 1.3× | Si el review detectó hallazgos que requieren cambios |
+| Complejidad creciente | 1.2× | Si los slices restantes son de mayor complejidad |
+
+## Dashboard
+
+```
+💰 Proyección de Costos — demo-sdd
+
+Slices completados: 3/5
+Tokens consumidos: 450K
+Costo acumulado: ~$13.50 (@ $0.03/1K tokens)
+
+Proyección:
+  Optimista (0.7×): + $6.30  → Total $19.80
+  Esperado  (1.0×): + $9.00  → Total $22.50
+  Pesimista (1.3×): + $11.70 → Total $25.20
+
+Budget máximo configurado: $30.00
+Estado: ✅ Dentro del budget (75% usado)
+```
+
+## Integración
+
+- Se calcula automáticamente al completar cada slice en `/especdev:implementar`
+- Se incluye en `/especdev:cerrar-sesion`
+- Si el costo proyectado excede el budget configurado, genera un `[checkpoint:decision]`

package/habilidades/prueba-trabajo/HABILIDAD.md

@@ -0,0 +1,131 @@
+---
+nombre: Prueba de Trabajo
+descripcion: "Generar evidencia verificable de que el código funciona: tests pasando, screenshots, logs"
+version: 1.0.0
+autor: Don Cheli
+tags: [verificación, evidencia, proof-of-work, ci]
+activacion: "prueba de trabajo", "evidencia", "proof of work", "demostrar que funciona"
+---
+
+# Habilidad: Prueba de Trabajo (Proof of Work)
+
+**Versión:** 1.0.0
+**Categoría:** Verificación
+**Tipo:** Rígida
+
+> Adaptado de OpenAI Symphony — evidencia verificable de que el trabajo fue completado correctamente.
+
+## Cómo Mejora el Framework
+
+Sin prueba de trabajo, el equipo debe revisar TODO el código manualmente para verificar que funciona. Con prueba de trabajo, el agente **demuestra** que su implementación es correcta con evidencia verificable.
+
+## Componentes de la Prueba de Trabajo
+
+### 1. Estado de CI ✅
+
+```markdown
+## CI Status
+- Lint: ✅ PASS (0.8s)
+- Type Check: ✅ PASS (2.1s)
+- Unit Tests: ✅ PASS (47/47, 3.2s)
+- Integration Tests: ✅ PASS (12/12, 8.5s)
+- Build: ✅ PASS (5.1s)
+- Coverage: 87% (umbral: 85%) ✅
+```
+
+### 2. Análisis de Complejidad 📊
+
+```markdown
+## Análisis de Complejidad
+- Archivos modificados: 8
+- Líneas agregadas: 234
+- Líneas eliminadas: 45
+- Complejidad ciclomática promedio: 3.2 (bajo)
+- Archivo más complejo: auth_service.py (cc: 7)
+- Dependencias nuevas: 1 (python-jose)
+- Riesgo de regresión: BAJO
+```
+
+### 3. Revisión de PR 📋
+
+```markdown
+## Checklist de PR
+- [x] Specs seguidas: auth-oauth.delta.md
+- [x] Tests unitarios para lógica nueva
+- [x] Tests de integración para endpoints
+- [x] No hay TODO/FIXME sin resolver
+- [x] Documentación actualizada
+- [x] No hay secrets en el código
+- [x] Backward compatible
+```
+
+### 4. Video Walkthrough 🎥 (Opcional)
+
+Grabación del agente ejecutando los tests y mostrando que la funcionalidad opera correctamente. Especialmente útil para cambios de UI.
+
+### 5. Contabilidad de Tokens 💰
+
+```markdown
+## Consumo de Recursos
+- Tokens input: 45,230
+- Tokens output: 12,890
+- Tokens total: 58,120
+- Sesiones: 2
+- Tiempo total: 7m 23s
+- Reintentos: 0
+- Costo estimado: $0.14
+```
+
+## Output Completo
+
+Cada PR o tarea completada incluye un archivo `prueba-trabajo.md`:
+
+```markdown
+# Prueba de Trabajo: PROJ-42 — Agregar OAuth
+
+## Resumen
+Feature implementada según spec auth-oauth.delta.md.
+3 endpoints nuevos, 12 tests, 0 bugs.
+
+## CI Status
+✅ Lint | ✅ Types | ✅ Tests (47/47) | ✅ Build | ✅ Coverage (87%)
+
+## Complejidad
+8 archivos | +234 -45 líneas | CC promedio: 3.2 | Riesgo: BAJO
+
+## Trazabilidad
+| Escenario Gherkin | Test | Estado |
+|-------------------|------|--------|
+| Login Google exitoso | test_google_login_success | ✅ |
+| Tarjeta rechazada | test_card_declined | ✅ |
+| Vincular OAuth a existente | test_link_oauth | ✅ |
+
+## Tokens
+58,120 tokens | 2 sesiones | 7m 23s | ~$0.14
+
+## Aprobación
+Estado: LISTO PARA REVISIÓN HUMANA
+Solicitante: Don Cheli Agent
+Fecha: 2026-03-21T16:30:00-05:00
+```
+
+## Integración con Pipeline
+
+```
+implementar → stop hooks → generar prueba-trabajo.md
+    → crear PR con prueba adjunta
+    → solicitar revisión humana
+    → si aprobada → archivar
+```
+
+## Configuración
+
+```yaml
+# WORKFLOW.md
+prueba_trabajo:
+  ci_status: true          # Siempre
+  complejidad: true         # Siempre
+  trazabilidad: true        # Siempre
+  walkthrough_video: false  # Opcional
+  tokens: true              # Siempre
+```

package/habilidades/razonamiento/HABILIDAD.md

@@ -0,0 +1,69 @@
+---
+nombre: Razonamiento (15 modelos + RLM)
+descripcion: "Aplicar modelos mentales estructurados para resolver problemas complejos de forma sistemática"
+version: 1.0.0
+autor: Don Cheli
+tags: [razonamiento, modelos-mentales, decision, analisis]
+activacion: "razonar", "analizar problema", "modelo mental", "pensar mejor"
+---
+
+# Habilidad: Razonamiento (15 modelos + RLM)
+
+**Versión:** 1.0.0
+**Categoría:** Decisiones
+**Tipo:** Flexible
+
+## Modelos Disponibles
+
+### Modelos de Análisis (Entender)
+| # | Modelo | Comando | Uso |
+|---|--------|---------|-----|
+| 1 | Primeros Principios | `/razonar:primeros-principios` | Innovación |
+| 2 | 5 Porqués | `/razonar:5-porques` | Causa raíz |
+| 3 | Mapa vs Territorio | `/razonar:mapa-territorio` | Validar suposiciones |
+
+### Modelos de Decisión (Elegir)
+| # | Modelo | Comando | Uso |
+|---|--------|---------|-----|
+| 4 | Pareto | `/razonar:pareto` | Priorización |
+| 5 | Costo de Oportunidad | `/razonar:costo-oportunidad` | Trade-offs |
+| 6 | Reversibilidad | `/razonar:reversibilidad` | Compromiso |
+| 7 | Minimizar Arrepentimiento | `/razonar:minimizar-arrepentimiento` | Largo plazo |
+| 8 | Probabilístico | `/razonar:probabilistico` | Incertidumbre |
+
+### Modelos de Perspectiva (Pensar)
+| # | Modelo | Comando | Uso |
+|---|--------|---------|-----|
+| 9 | Inversión | `/razonar:inversion` | Pensar al revés |
+| 10 | Segundo Orden | `/razonar:segundo-orden` | Pensar adelante |
+| 11 | Pre-Mortem | `/razonar:pre-mortem` | Pensar fracaso |
+| 12 | Círculo de Competencia | `/razonar:circulo-competencia` | Pensar límites |
+
+### 🧠 Modelos RLM (Modelo de Lenguaje Recursivo — PrimeIntellect)
+| # | Modelo | Comando | Uso |
+|---|--------|---------|-----|
+| 13 | Verificación con Sub-LLMs | `/razonar:rlm-verificacion` | Verificar código contra specs |
+| 14 | Cadena + Context Folding | `/razonar:rlm-cadena-pensamiento` | Razonamiento multi-paso sin context rot |
+| 15 | Descomposición Recursiva | `/razonar:rlm-descomposicion` | Inputs masivos, codebases grandes |
+
+## Árbol de Decisión
+
+```
+¿Qué tipo de problema tengo?
+├── No entiendo el problema → Análisis
+│   ├── Suposiciones → primeros-principios
+│   ├── Bug/Error → 5-porques
+│   └── Datos confusos → mapa-territorio
+├── Necesito elegir → Decisión
+│   ├── Qué priorizar → pareto
+│   ├── Qué compromiso → reversibilidad / probabilístico
+│   └── Largo plazo → minimizar-arrepentimiento
+├── Necesito perspectiva → Perspectiva
+│   ├── Evitar fracaso → pre-mortem / inversión
+│   ├── Ver más allá → segundo-orden
+│   └── ¿Sé lo suficiente? → circulo-competencia
+└── Necesito manejar contexto largo / input masivo → RLM
+    ├── Verificar contra specs → rlm-verificacion
+    ├── Razonamiento multi-paso → rlm-cadena-pensamiento
+    └── Codebase grande / datos masivos → rlm-descomposicion
+```

package/habilidades/recuperacion-sesion/HABILIDAD.md

@@ -0,0 +1,27 @@
+---
+nombre: Recuperación de Sesión
+descripcion: "Recuperar el contexto de una sesión previa leyendo artifacts del disco y generando briefing"
+version: 1.0.0
+autor: Don Cheli
+tags: [fundamental, sesión, contexto, recuperación, memoria]
+activacion: "recuperar sesión", "continuar donde dejé", "qué estaba haciendo"
+---
+
+# Habilidad: Recuperación de Sesión
+
+**Versión:** 1.0.0
+**Categoría:** Fundamental
+
+## Propósito
+
+Recuperar contexto completo tras reset de sesión usando los archivos persistentes.
+
+## Test de 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 |

package/habilidades/refactorizacion-solid/HABILIDAD.md

@@ -0,0 +1,182 @@
+---
+nombre: Refactorización SOLID
+descripcion: "Guiar refactoring con principios SOLID: checklist de violaciones, métricas, patrones de diseño"
+version: 1.0.0
+autor: Don Cheli
+tags: [calidad, SOLID, refactoring, clean-code, patrones]
+activacion: "refactorizar SOLID", "principios SOLID", "code smells", "refactoring"
+---
+
+# Habilidad: Refactorización SOLID y Clean Code
+
+**Versión:** 1.0.0
+**Categoría:** Calidad
+**Tipo:** Flexible
+
+## Cómo Mejora el Framework
+
+Don Cheli tiene la Constitución (Art. II: Precisión Quirúrgica, Art. III: Plug-and-Play) que define principios, pero no provee un proceso estructurado para refactorizar código existente aplicando patrones de diseño y principios SOLID.
+
+## Cuándo Activar
+
+- Al detectar code smells durante `/especdev:revisar`
+- Cuando un módulo supera umbrales de complejidad
+- Antes de agregar funcionalidad a código legacy
+- Cuando el usuario solicita refactorización explícitamente
+
+## Los 5 Principios SOLID como Checklist
+
+### S — Single Responsibility (Responsabilidad Única)
+
+```
+Verificar: ¿Tiene la clase/módulo una sola razón para cambiar?
+
+Smells:
+  ❌ Clase con > 200 líneas
+  ❌ Más de 3 dependencias inyectadas
+  ❌ Nombre genérico (Manager, Helper, Utils, Handler)
+  ❌ Múltiples secciones con comentarios "// --- Sección X ---"
+
+Fix: Extraer a clases/módulos especializados
+  UserService → UserCreator + UserValidator + UserNotifier
+```
+
+### O — Open/Closed (Abierto/Cerrado)
+
+```
+Verificar: ¿Se puede extender sin modificar código existente?
+
+Smells:
+  ❌ Cadenas if/else o switch crecientes
+  ❌ Modificar clase existente para cada nueva variante
+  ❌ Parámetros booleanos que cambian comportamiento
+
+Fix: Strategy pattern, Plugin pattern, Registry pattern
+  if (type === 'credit') {...} else if (type === 'debit') {...}
+  → paymentStrategies[type].process(data)
+```
+
+### L — Liskov Substitution (Sustitución de Liskov)
+
+```
+Verificar: ¿Las subclases pueden reemplazar a la clase padre sin romper nada?
+
+Smells:
+  ❌ Subclase que lanza NotImplementedError en método heredado
+  ❌ instanceof checks en código que usa la abstracción
+  ❌ Override que cambia la semántica del método padre
+
+Fix: Rediseñar jerarquía, usar composición sobre herencia
+  Square extends Rectangle (rompe Liskov)
+  → Shape interface con área() independiente
+```
+
+### I — Interface Segregation (Segregación de Interfaces)
+
+```
+Verificar: ¿Las interfaces son específicas o fuerzan a implementar métodos innecesarios?
+
+Smells:
+  ❌ Interfaces con > 5 métodos
+  ❌ Implementaciones con métodos vacíos o throw
+  ❌ "God interface" que mezcla concerns
+
+Fix: Dividir en interfaces específicas
+  IUserService (create, read, update, delete, sendEmail, generateReport)
+  → IUserCRUD + IUserNotification + IUserReporting
+```
+
+### D — Dependency Inversion (Inversión de Dependencias)
+
+```
+Verificar: ¿Los módulos de alto nivel dependen de abstracciones, no de implementaciones?
+
+Smells:
+  ❌ new ConcreteService() dentro de otra clase
+  ❌ Import directo de implementación concreta
+  ❌ Tests que requieren infraestructura real
+
+Fix: Inyección de dependencias
+  class AuthService { db = new PostgresDB() }
+  → class AuthService { constructor(private db: IDatabase) }
+```
+
+## Patrones de Diseño — Cuándo Aplicar
+
+| Patrón | Cuándo Usar | Ejemplo |
+|--------|------------|---------|
+| **Factory** | Creación de objetos con lógica condicional | `createPaymentProcessor(type)` |
+| **Strategy** | Algoritmos intercambiables | Múltiples métodos de envío |
+| **Observer** | Notificación de cambios sin acoplamiento | Eventos de dominio |
+| **Adapter** | Integrar interfaces incompatibles | Wrapper para API externa |
+| **Repository** | Abstraer acceso a datos | `UserRepository` interface |
+| **Decorator** | Agregar comportamiento sin modificar | Logging, caching, retry |
+| **Builder** | Construir objetos complejos paso a paso | Query builder, config builder |
+| **Facade** | Simplificar subsistema complejo | `PaymentFacade` sobre Stripe+Tax+Invoice |
+
+**Regla:** Aplicar un patrón solo cuando el smell existe. Nunca aplicar preventivamente.
+
+## Proceso de Refactorización
+
+```
+1. IDENTIFICAR — Detectar smells con análisis estático
+   └── Complejidad ciclomática, acoplamiento, cohesión
+
+2. PLANIFICAR — Definir qué principio/patrón aplicar
+   └── [REGLA 4: Si cambia arquitectura → PARAR Y PREGUNTAR]
+
+3. PROTEGER — Asegurar que hay tests antes de refactorizar
+   └── Si no hay tests → escribirlos primero (Ley de Hierro #1)
+
+4. REFACTORIZAR — Aplicar cambio mínimo viable (Art. II Constitución)
+   └── Un patrón a la vez, nunca varios simultáneos
+
+5. VERIFICAR — Ejecutar tests, verificar que pasan
+   └── Cero cambio de comportamiento (Ley de Hierro #3)
+```
+
+## Métricas de Código
+
+| Métrica | Umbral Aceptable | Umbral Refactorizar |
+|---------|------------------|---------------------|
+| Complejidad ciclomática | ≤ 10 | > 15 |
+| Líneas por función | ≤ 30 | > 50 |
+| Líneas por archivo | ≤ 300 | > 500 |
+| Profundidad de anidamiento | ≤ 3 | > 4 |
+| Parámetros por función | ≤ 3 | > 5 |
+| Dependencias por módulo | ≤ 5 | > 7 |
+
+## Output del Análisis
+
+```markdown
+## Análisis de Refactorización: src/services/order_service.py
+
+### Smells Detectados
+
+| # | Smell | Principio | Severidad | Líneas |
+|---|-------|-----------|-----------|--------|
+| 1 | Clase de 450 líneas con 12 métodos | S (SRP) | ❌ Alto | 1-450 |
+| 2 | Switch de 8 casos para tipo de pago | O (OCP) | ⚠️ Medio | 120-180 |
+| 3 | `new StripeClient()` hardcoded | D (DIP) | ⚠️ Medio | 45 |
+
+### Plan de Refactorización
+
+1. **Extraer** validaciones → `OrderValidator` (SRP)
+2. **Extraer** cálculos → `OrderCalculator` (SRP)
+3. **Strategy** para tipos de pago → `PaymentStrategy` interface (OCP)
+4. **Inyectar** StripeClient via constructor (DIP)
+
+### Impacto Estimado
+- Archivos afectados: 4 (crear 3 nuevos, modificar 1)
+- Tests a actualizar: 6
+- Riesgo: Bajo (cambio de estructura, no de comportamiento)
+```
+
+## Guardrails
+
+- **Nunca** refactorizar sin tests existentes — escribirlos primero
+- **Nunca** aplicar múltiples patrones en un solo PR
+- **Nunca** refactorizar "de paso" junto a una feature (Art. II)
+- **Siempre** verificar cero cambio de comportamiento post-refactor
+- **Siempre** pedir confirmación si afecta > 5 archivos (Regla 4)
+- **Siempre** justificar el patrón elegido vs alternativa más simple