don-cheli-sdd 1.13.0

package/scripts/.claude/commands/especdev/minar-referencias.md

@@ -0,0 +1,214 @@
+---
+description: Buscar repos open-source relevantes como referencia antes de implementar
+i18n: true
+---
+
+# /especdev:minar-referencias
+
+## Objetivo
+
+Buscar y evaluar repositorios open-source, snippets y patrones de referencia relevantes para la tarea actual. Reduce el "empezar de cero" proporcionando implementaciones probadas como guía.
+
+> Adaptado de DeepCode (HKUDS/DeepCode) — Code Reference Mining Agent: "descubrir repositorios relevantes y construir knowledge graphs para informar la generación de código."
+
+## Uso
+
+```
+/especdev:minar-referencias "webhook handler con verificación de firma"
+/especdev:minar-referencias "rate limiter con sliding window"
+/especdev:minar-referencias --stack node,typescript "auth con JWT refresh"
+/especdev:minar-referencias --max 5 "graphql subscriptions"
+```
+
+## Por Qué Existe
+
+| Sin Minar | Con Minar |
+|-----------|-----------|
+| Implementar desde cero | Partir de patrones probados |
+| Descubrir anti-patrones tarde | Conocer pitfalls de antemano |
+| Reinventar soluciones comunes | Reutilizar lo que funciona |
+| Estimaciones imprecisas | Complejidad real visible |
+
+## Comportamiento
+
+### Paso 1: Análisis de la Query
+
+```
+Query: "webhook handler con verificación de firma"
+├── Conceptos clave: webhook, handler, signature verification
+├── Stack detectado: Node.js + TypeScript (de config.yaml)
+├── Dominio: API integration, security
+└── Complejidad estimada: Media
+```
+
+### Paso 2: Búsqueda Multi-Fuente
+
+El comando busca en múltiples fuentes (según disponibilidad):
+
+| Fuente | Método | Qué Busca |
+|--------|--------|-----------|
+| **GitHub** | API search / web search | Repos con implementaciones similares |
+| **Proyecto actual** | Grep local | Código existente reutilizable |
+| **CodeRAG** | Índice local | Patrones ya indexados |
+| **Memoria** | Engram | Decisiones previas sobre el tema |
+
+### Paso 3: Evaluación de Relevancia
+
+Cada resultado se evalúa en 4 dimensiones:
+
+| Dimensión | Peso | Criterio |
+|-----------|------|----------|
+| **Relevancia** | 40% | ¿Resuelve el mismo problema? |
+| **Calidad** | 25% | Stars, mantenimiento, tests, docs |
+| **Compatibilidad** | 20% | ¿Mismo stack/framework? |
+| **Simplicidad** | 15% | ¿Es adoptable sin refactor mayor? |
+
+Score = suma ponderada (0.0 - 1.0)
+
+### Paso 4: Extracción de Patrones
+
+De los top resultados, se extraen:
+
+```
+1. Patrón arquitectónico usado
+2. Dependencias clave
+3. Manejo de errores
+4. Edge cases cubiertos
+5. Snippet representativo (≤ 30 líneas)
+```
+
+## Output
+
+```markdown
+## Referencias Minadas: "webhook handler con verificación de firma"
+
+Fecha: 2026-03-21 | Stack: Node.js + TypeScript | Resultados: 3
+
+---
+
+### 1. stripe/stripe-node — Webhook Verification (score: 0.91)
+**Repo:** github.com/stripe/stripe-node
+**Archivo:** src/Webhooks.ts
+**Por qué es relevante:** Implementación de referencia de Stripe para verificar firmas HMAC-SHA256.
+
+**Patrón:**
+- Verificar firma antes de procesar
+- Tolerancia de timestamp (5 min por defecto)
+- Comparación timing-safe para prevenir timing attacks
+
+**Snippet:**
+```typescript
+function verifySignature(payload: string, header: string, secret: string): boolean {
+  const timestamp = extractTimestamp(header);
+  const signature = extractSignature(header);
+
+  if (Date.now() / 1000 - timestamp > TOLERANCE) {
+    throw new WebhookSignatureError('Timestamp too old');
+  }
+
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(`${timestamp}.${payload}`)
+    .digest('hex');
+
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+```
+
+**Lecciones:**
+- Usar `timingSafeEqual` (no `===`) para comparar firmas
+- Validar timestamp para prevenir replay attacks
+- Lanzar error específico (no genérico)
+
+---
+
+### 2. svix/svix-webhooks — Webhook Handler Pattern (score: 0.84)
+**Repo:** github.com/svix/svix-webhooks
+**Por qué es relevante:** SDK de webhooks con patrón de handler idempotente.
+
+**Patrón:**
+- Idempotency key en header
+- Queue para procesamiento async
+- Retry automático con backoff
+
+**Lecciones:**
+- Separar verificación de procesamiento
+- Idempotencia es obligatoria para webhooks
+- Responder 200 antes de procesar (async)
+
+---
+
+### 3. [Proyecto actual] src/utils/crypto.ts (score: 0.72)
+**Archivo:** src/utils/crypto.ts:15-30
+**Por qué es relevante:** Ya existe un helper de HMAC en el proyecto.
+
+**Nota:** Reutilizar `createHmacSignature()` existente en vez de reimplementar.
+
+---
+
+## Resumen de Decisiones
+
+| Decisión | Recomendación | Fuente |
+|----------|--------------|--------|
+| Verificación de firma | HMAC-SHA256 + timestamp | stripe/stripe-node |
+| Comparación de firma | `timingSafeEqual` | stripe/stripe-node |
+| Procesamiento | Async (queue) + responder 200 | svix/svix-webhooks |
+| Helper de HMAC | Reutilizar existente | Proyecto actual |
+| Idempotencia | Idempotency key en header | svix/svix-webhooks |
+
+## Próximo Paso
+→ `/especdev:especificar` usando estas referencias como base
+→ O `/especdev:planificar-tecnico` para incorporar los patrones al blueprint
+```
+
+## Integración con Pipeline
+
+```
+/especdev:minar-referencias → referencias
+  → /especdev:especificar → specs informadas
+  → /especdev:planificar-tecnico → plan con patrones reales
+  → CodeRAG → indexar patrones útiles para futuro
+
+/especdev:minar-referencias → referencias
+  → /especdev:estimar → estimados más precisos (complejidad real)
+```
+
+## Integración con CodeRAG
+
+Los patrones encontrados se pueden indexar automáticamente:
+
+```
+¿Indexar los patrones encontrados en CodeRAG? (s/n)
+> s
+Indexados 3 patrones en .especdev/code-rag/patterns.json
+```
+
+## Almacenamiento
+
+```
+.especdev/referencias/
+├── webhook-handler-2026-03-21.md    # Resultado de esta búsqueda
+├── rate-limiter-2026-03-15.md       # Búsqueda anterior
+└── _index.md                        # Índice de búsquedas
+```
+
+## Modelo Recomendado
+
+| Paso | Modelo | Razón |
+|------|--------|-------|
+| Búsqueda | Haiku | Solo buscar y filtrar |
+| Evaluación de relevancia | Haiku | Scoring simple |
+| Extracción de patrones | Sonnet | Requiere comprensión de código |
+| Resumen de decisiones | Haiku | Formateo |
+
+## Guardrails
+
+- **Nunca** copiar código con licencias incompatibles sin verificar
+- **Nunca** incluir credenciales o tokens de repos de referencia
+- **Siempre** priorizar código existente en el proyecto sobre externo
+- **Siempre** indicar la fuente y licencia de cada referencia
+- **Siempre** limitar snippets a ≤30 líneas (respetar fair use)
+- **Máximo** 5 referencias por búsqueda (evitar analysis paralysis)

package/scripts/.claude/commands/especdev/planificar-tecnico.md

@@ -0,0 +1,186 @@
+---
+description: Generar blueprint técnico desde una especificación Gherkin
+i18n: true
+---
+
+# /especdev:planificar-tecnico
+
+## Objetivo
+
+Generar un blueprint técnico (contratos API, modelos, arquitectura de servicios) desde una especificación Gherkin, incluyendo verificación de constitución y contexto técnico estructurado.
+
+> Alineado con spec-kit (github/spec-kit) — Constitution Check, Technical Context y Complexity Tracking
+
+## Uso
+
+```
+/especdev:planificar-tecnico @specs/features/<dominio>/<Feature>.feature
+```
+
+## Comportamiento
+
+1. **Verificar Puerta 2** — El `.feature` debe tener tag `@lista` (pasó `/especdev:clarificar`)
+2. **Verificar** que no hay marcadores `[NECESITA CLARIFICACIÓN]` pendientes
+3. **Ejecutar Chequeo de Constitución** — Validar contra los principios de `reglas/constitucion.md`
+4. **Documentar Contexto Técnico** — Stack, dependencias, restricciones
+5. **Ratificar DBML** — Convertir campos `@provisional` a ratificados
+6. **Generar** contratos API, modelos, arquitectura de servicios
+7. **Registrar Complejidad** — Justificar desviaciones de simplicidad
+8. **Crear** archivo `.plan.md` en `specs/features/<dominio>/`
+
+## Output
+
+Genera `specs/features/<dominio>/<Feature>.plan.md`:
+
+```markdown
+# Blueprint Técnico: CrearUsuario
+
+**Rama:** feature/crear-usuario
+**Spec:** specs/features/usuario/CrearUsuario.feature
+**Fecha:** 2026-03-21
+**Estado:** Borrador
+
+---
+
+## Resumen
+
+Implementar registro de usuarios con email/contraseña, incluyendo
+validación, hashing de contraseña y generación de JWT.
+Enfoque técnico: API REST con patrón Controller → Service → Repository.
+
+---
+
+## Chequeo de Constitución
+
+Verificación obligatoria contra `reglas/constitucion.md`:
+
+| Artículo | Principio | Estado | Notas |
+|----------|-----------|--------|-------|
+| I | Gherkin es Rey | ✅ | Spec @lista aprobada |
+| I-B | Schema como Verdad Viva | ✅ | DBML ratificado |
+| II | Precisión Quirúrgica | ✅ | Cambio mínimo, 1 feature |
+| III | Arquitectura Plug-and-Play | ✅ | Nuevo módulo, no infla existentes |
+| IV | Regla Las Vegas | ✅ | Tests herméticos planificados |
+| IV-B | Punto de Entrada | ✅ | Validación en Controller |
+| V | Estándares Modernos | ✅ | Type hints + Pydantic/Zod |
+| VI | Adaptabilidad | ✅ | Stack detectado: FastAPI |
+| VII | Codificación Defensiva | ✅ | Excepciones custom planificadas |
+
+**Resultado: ✅ PASA** — El plan es compatible con la constitución.
+
+---
+
+## Contexto Técnico
+
+| Aspecto | Valor |
+|---------|-------|
+| **Lenguaje** | Python 3.12 / TypeScript 5.x |
+| **Framework** | FastAPI 0.115 / Next.js 15 |
+| **Dependencias** | bcryptjs, python-jose, pydantic |
+| **Almacenamiento** | PostgreSQL 16 + Prisma/SQLAlchemy |
+| **Testing** | pytest + pytest-asyncio / vitest |
+| **Plataforma** | Docker + Linux |
+| **Rendimiento** | < 500ms p95 (de criterios de éxito) |
+| **Escala** | ~1,000 registros/día (estimado) |
+| **Restricciones** | Sin OAuth en v1 (definido en clarificación) |
+
+---
+
+## Contrato API
+
+POST /api/v1/usuarios
+Content-Type: application/json
+
+Request:
+{
+  "email": "string (required, email format)",
+  "password": "string (required, min 8 chars)",
+  "nombre": "string (required, max 100 chars)"
+}
+
+Response 201:
+{
+  "id": "uuid",
+  "email": "string",
+  "nombre": "string",
+  "token": "jwt-string",
+  "createdAt": "datetime"
+}
+
+Response 400:
+{
+  "error": "string",
+  "field": "string (optional)"
+}
+
+Response 409:
+{
+  "error": "El email ya está registrado"
+}
+
+---
+
+## Modelo de Datos
+
+Usuario (ratificado desde DBML):
+  - id: UUID (PK, auto-gen)
+  - email: String (unique, indexed, NOT NULL)
+  - password_hash: String (NOT NULL)
+  - nombre: String (max 100, NOT NULL)
+  - created_at: DateTime (default: now())
+
+---
+
+## Arquitectura de Servicios
+
+Controller → Service → Repository → Database
+                 ↓
+           EmailService (async)
+
+---
+
+## Dependencias
+
+- bcryptjs (hash de contraseña)
+- python-jose / jsonwebtoken (generación JWT)
+- pydantic / zod (validación de DTOs)
+
+---
+
+## Tracking de Complejidad
+
+Justificar cualquier decisión que añade complejidad por encima de la alternativa más simple:
+
+| Decisión | Alternativa Simple | Por Qué Se Rechazó |
+|----------|--------------------|---------------------|
+| JWT con refresh token | Solo JWT simple | Requerimiento de seguridad: tokens de corta duración |
+| Email async con cola | Email síncrono | Bloquea respuesta al usuario, riesgo de timeout |
+| Repository pattern | Queries directas | Testabilidad: inyección de dependencias para mocks |
+
+Si la tabla está vacía, no hay desviaciones de simplicidad.
+```
+
+## Secciones Obligatorias del Plan
+
+| Sección | Propósito | Falla si falta |
+|---------|-----------|----------------|
+| **Resumen** | Qué y cómo en 2-3 líneas | Sí |
+| **Chequeo de Constitución** | Validar contra principios | Sí |
+| **Contexto Técnico** | Stack y restricciones | Sí |
+| **Contrato API** | Interfaces públicas | Sí (si hay API) |
+| **Modelo de Datos** | Entidades y relaciones | Sí (si hay datos) |
+| **Arquitectura** | Componentes y flujo | Sí |
+| **Dependencias** | Librerías externas | Sí |
+| **Tracking de Complejidad** | Justificar desviaciones | Sí (puede estar vacía) |
+
+## Puerta de Calidad
+
+Este comando implementa la **Puerta 4 (Aprobación de Plan)**:
+
+- Chequeo de constitución pasa (todos ✅)
+- Sin `[NECESITA CLARIFICACIÓN]` pendiente
+- Contexto técnico completo
+- DBML ratificado (sin campos `@provisional`)
+- Tracking de complejidad documentado
+
+Si algún artículo de la constitución no pasa → **NO-AVANZAR** hasta resolver.

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

@@ -0,0 +1,264 @@
+---
+description: Planning semanal de equipo con revisión de RFCs, priorización, asignación por responsable/pareja/squad y seguimiento
+i18n: true
+---
+
+# /especdev:planning
+
+## Objetivo
+
+Facilitar el planning semanal de un equipo de desarrollo: revisar RFCs pendientes, priorizar trabajo, asignar tareas a responsables individuales, parejas o squads, y generar un plan accionable con compromisos claros.
+
+A diferencia de `/especdev:estimar` (esfuerzo por tarea) o `/especdev:debate` (decisiones técnicas), el planning opera a **nivel de equipo y sprint**: qué se hace, quién lo hace, en qué orden, y qué se deja fuera.
+
+## Uso
+
+```
+/especdev:planning                                    # Planning completo (interactivo)
+/especdev:planning --semana "2026-03-24"              # Planning para semana específica
+/especdev:planning --equipo "Ana,Carlos,Luis,María"   # Definir equipo
+/especdev:planning --capacidad "Ana:4d,Carlos:3d"     # Capacidad por persona (días disponibles)
+/especdev:planning --rfcs "RFC-012,RFC-015,RFC-018"   # RFCs a revisar
+/especdev:planning --modo revision                    # Solo revisión de RFCs (sin asignación)
+/especdev:planning --modo asignacion                  # Solo asignación (RFCs ya priorizados)
+/especdev:planning --modo seguimiento                 # Revisar avance del planning anterior
+```
+
+## Proceso (4 Fases)
+
+### Fase 1: Contexto del equipo
+
+Recopilar información del equipo antes de planificar:
+
+```markdown
+## Contexto del equipo
+
+### Miembros y disponibilidad
+| Miembro | Rol | Disponibilidad | Notas |
+|---------|-----|----------------|-------|
+| Ana | Sr. Backend | 4/5 días | Lunes feriado |
+| Carlos | Sr. Frontend | 5/5 días | — |
+| Luis | Fullstack | 3/5 días | 2 días en soporte rotativo |
+| María | Sr. Backend | 5/5 días | — |
+| Diego | Jr. Frontend | 5/5 días | Necesita mentoring |
+
+### Capacidad total del equipo
+- Días disponibles: 22/25 (88%)
+- Factor de foco (reuniones, interrupciones): 0.7
+- **Capacidad efectiva: 15.4 días-persona**
+
+### Arrastre de la semana anterior
+- [ ] RFC-010: Migración de auth — 60% completado (María, bloqueo en revisión de seguridad)
+- [x] RFC-011: Endpoint de reportes — completado
+- [ ] BUG-234: Memory leak en worker — pendiente (Luis no tuvo disponibilidad)
+```
+
+### Fase 2: Revisión de RFCs
+
+Evaluar cada RFC pendiente con criterios estructurados:
+
+```markdown
+## Revisión de RFCs
+
+### RFC-012: Cache distribuido con Redis
+- **Autor:** María | **Estado:** Aprobado | **Tamaño:** L
+- **Dependencias:** Infra debe provisionar Redis cluster
+- **Riesgo técnico:** Medio (equipo no tiene experiencia con Redis Cluster)
+- **Impacto de negocio:** Alto (reduce latencia de catálogo de 800ms a 200ms)
+- **Deuda técnica:** Baja (solución limpia, bien diseñada)
+- **Veredicto:** ✅ Priorizar esta semana
+
+### RFC-015: Migración de Styled Components a Tailwind
+- **Autor:** Carlos | **Estado:** En discusión | **Tamaño:** XL
+- **Dependencias:** Ninguna técnica, pero necesita buy-in del equipo de diseño
+- **Riesgo técnico:** Bajo (migración incremental posible)
+- **Impacto de negocio:** Bajo (mejora DX, no impacta usuario final)
+- **Deuda técnica:** Media (reduce deuda futura pero introduce churn ahora)
+- **Veredicto:** ⏸️ Postergar — no justifica el costo de oportunidad esta semana
+
+### RFC-018: API de notificaciones push
+- **Autor:** Ana | **Estado:** Aprobado | **Tamaño:** M
+- **Dependencias:** RFC-012 (necesita Redis para pub/sub)
+- **Riesgo técnico:** Bajo
+- **Impacto de negocio:** Alto (feature pedido por 3 clientes enterprise)
+- **Veredicto:** ✅ Priorizar después de RFC-012
+```
+
+### Fase 3: Priorización y asignación
+
+Usar matriz de priorización y asignar por modalidad:
+
+```markdown
+## Priorización (Eisenhower + WSJF)
+
+| # | Item | Urgente | Importante | WSJF Score | Decisión |
+|---|------|---------|------------|------------|----------|
+| 1 | BUG-234: Memory leak | ✅ | ✅ | — | **Primero** (producción) |
+| 2 | RFC-010: Auth (arrastre) | ✅ | ✅ | 8.5 | **Completar** (WIP) |
+| 3 | RFC-012: Redis cache | ❌ | ✅ | 7.2 | **Esta semana** |
+| 4 | RFC-018: Push notifications | ❌ | ✅ | 6.8 | **Iniciar si hay capacidad** |
+| 5 | RFC-015: Tailwind migration | ❌ | ❌ | 3.1 | **Backlog** |
+
+### WSJF (Weighted Shortest Job First)
+Score = (Valor de negocio + Urgencia + Reducción de riesgo) / Tamaño del trabajo
+- Valor: 1-5 | Urgencia: 1-5 | Riesgo: 1-5 | Tamaño: 1-5 (Fibonacci: 1,2,3,5,8)
+
+## Asignación
+
+### Modalidad: Individual
+Para tareas bien definidas donde una persona puede avanzar sola.
+
+| Tarea | Responsable | Estimado | Entregable | Deadline |
+|-------|-------------|----------|------------|----------|
+| BUG-234: Memory leak | Luis | 1d | Fix + test + post-mortem | Lunes |
+| RFC-010: Auth (completar) | María | 2d | PR listo para merge | Miércoles |
+
+### Modalidad: Pareja (Pair Programming)
+Para tareas que requieren conocimiento cruzado o mentoring.
+
+| Tarea | Pareja | Razón | Estimado | Entregable |
+|-------|--------|-------|----------|------------|
+| RFC-012: Redis cache (setup) | María + Luis | María diseñó el RFC, Luis aprende Redis | 2d | Infra + tests de integración |
+| RFC-012: Redis cache (frontend) | Carlos + Diego | Diego aprende patterns de caching en frontend, Carlos mentora | 1.5d | Cache invalidation UI + tests |
+
+### Modalidad: Squad
+Para iniciativas que necesitan esfuerzo coordinado multi-disciplina.
+
+| Iniciativa | Squad | Roles | Estimado | Sync |
+|------------|-------|-------|----------|------|
+| RFC-018: Push notifications | Ana (lead) + Carlos + María | Ana: API, Carlos: UI, María: pub/sub | 3d | Daily 15min a las 10:00 |
+```
+
+### Fase 4: Plan semanal consolidado
+
+```markdown
+## Plan Semanal: 2026-03-24 → 2026-03-28
+
+### Compromisos (lo que prometemos entregar)
+1. ✅ BUG-234 resuelto en producción (Lunes)
+2. ✅ RFC-010: Auth migración completada y mergeada (Miércoles)
+3. ✅ RFC-012: Redis cache funcional en staging (Viernes)
+
+### Stretch goals (si hay capacidad)
+4. 🎯 RFC-018: Push notifications — diseño de API + spike de pub/sub
+
+### Lo que NO hacemos esta semana (y por qué)
+- RFC-015: Tailwind migration — WSJF bajo, sin urgencia de negocio
+- TECH-089: Upgrade Node 22 — esperamos que el equipo de plataforma publique guía
+
+### Riesgos y mitigaciones
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|-------------|---------|------------|
+| Redis provisioning se demora | Media | Alto | María hace spike con Docker local primero |
+| Luis no termina BUG-234 el lunes | Baja | Alto | Ana como backup (conoce el worker) |
+| Revisión de seguridad de auth bloquea a María | Alta | Medio | Escalar a Tech Lead el martes si no hay review |
+
+### Ceremonias
+| Ceremonia | Día | Hora | Duración | Quién |
+|-----------|-----|------|----------|-------|
+| Planning (este documento) | Lunes | 09:00 | 45min | Todo el equipo |
+| Daily standup | L-V | 09:30 | 15min | Todo el equipo |
+| RFC-018 sync | M-J | 10:00 | 15min | Squad de push |
+| Demo/Review | Viernes | 16:00 | 30min | Todo el equipo + PM |
+
+### Métricas de la semana
+- Capacidad utilizada: 15.4 / 15.4 días-persona (100%)
+- Items comprometidos: 3
+- Stretch: 1
+- Carry-over anterior: 2 (BUG-234, RFC-010)
+```
+
+## Criterios de evaluación de RFCs
+
+Al revisar un RFC, evaluar cada dimensión con 1-5:
+
+| Dimensión | 1 (Bajo) | 5 (Alto) |
+|-----------|----------|----------|
+| **Impacto de negocio** | Nice-to-have interno | Bloquea revenue o cliente enterprise |
+| **Riesgo técnico** | Tecnología conocida, patrón probado | Stack nuevo, sin experiencia en el equipo |
+| **Tamaño** | < 1 día, 1-2 archivos | > 1 semana, cross-cutting |
+| **Urgencia** | Sin deadline, puede esperar | SLA comprometido o dependencia bloqueante |
+| **Deuda técnica** | Solución limpia | Workaround que acumula deuda |
+
+## Reglas del Planning
+
+### Regla de capacidad
+**NUNCA planificar al 100% de capacidad.** Factor de foco:
+- Equipo maduro con pocos meetings: **0.8**
+- Equipo promedio: **0.7**
+- Equipo con mucho soporte/on-call: **0.5-0.6**
+
+### Regla de WIP
+Máximo **2 items en progreso por persona**. Si alguien tiene 2 tareas activas, no se le asigna una tercera hasta que cierre una.
+
+### Regla de arrastre
+Si un item se arrastra **3 semanas consecutivas**, se debe tomar una decisión:
+1. **Replantear**: dividir en partes más pequeñas
+2. **Escalar**: pedir ayuda o más recursos
+3. **Cancelar**: admitir que no es prioridad y sacarlo del backlog
+
+### Regla de parejas
+Las parejas DEBEN rotar cada semana. Objetivo: ningún conocimiento queda en una sola persona.
+
+### Regla de juniors
+Todo junior DEBE estar asignado en pareja con un senior. Nunca asignar tareas críticas a un junior solo.
+
+## Almacenamiento
+
+```
+.especdev/
+├── plannings/
+│   ├── 2026-W13.md        # Planning semana 13
+│   ├── 2026-W14.md        # Planning semana 14
+│   └── _retrospectiva.md  # Patrones observados entre plannings
+└── rfcs/
+    ├── RFC-012.md          # RFC individual
+    ├── RFC-015.md
+    └── _indice.md          # Índice de todos los RFCs con estado
+```
+
+## Modos especiales
+
+### `--modo revision`
+Solo ejecuta Fases 1 y 2 (contexto + revisión de RFCs). Útil para sesiones de refinamiento mid-week.
+
+### `--modo asignacion`
+Solo ejecuta Fases 3 y 4 (priorización + plan). Asume que los RFCs ya fueron revisados.
+
+### `--modo seguimiento`
+Lee el planning de la semana actual (`.especdev/plannings/`) y genera reporte de avance:
+```markdown
+## Seguimiento: Semana 2026-W13 (Jueves)
+
+### Avance
+| Item | Estado | Progreso | Notas |
+|------|--------|----------|-------|
+| BUG-234 | ✅ Completado | 100% | Mergeado lunes, post-mortem hecho |
+| RFC-010: Auth | 🟡 En progreso | 80% | Review de seguridad pendiente |
+| RFC-012: Redis | 🟢 En progreso | 40% | Setup OK, tests de integración en progreso |
+| RFC-018: Push | ⬜ No iniciado | 0% | Depende de RFC-012, se inicia viernes si hay tiempo |
+
+### Alerta
+- RFC-010 lleva 2 semanas de carry-over. Si no se completa esta semana → regla de arrastre.
+- Capacidad real utilizada: 12/15.4 días (78%) — 2 días perdidos en incidente no planificado.
+```
+
+## Integración con otros comandos
+
+| Comando | Cuándo usarlo junto con planning |
+|---------|----------------------------------|
+| `/especdev:estimar` | Para estimar RFCs grandes antes del planning |
+| `/especdev:debate` | Para resolver desacuerdos técnicos sobre un RFC |
+| `/especdev:mesa-tecnica` | Para profundizar en la implementación de un RFC priorizado |
+| `/especdev:desglosar` | Para dividir un RFC priorizado en tareas TDD |
+| `/especdev:contrato-api` | Para definir interfaces antes de asignar a parejas/squads |
+
+## Modelo recomendado
+
+| Paso | Modelo | Razón |
+|------|--------|-------|
+| Contexto y capacidad | Haiku | Cálculos y formateo |
+| Revisión de RFCs | Sonnet | Juicio técnico para evaluar riesgo/impacto |
+| Priorización WSJF | Sonnet | Razonamiento sobre trade-offs |
+| Asignación | Haiku | Matcheo persona-tarea según datos |
+| Plan consolidado | Haiku | Formateo y consolidación |