don-cheli-sdd 1.13.0

package/scripts/.claude/commands/especdev/contrato-ui.md

@@ -0,0 +1,245 @@
+---
+description: Bloquear estándares visuales antes de codear frontend (UI Design Contract)
+i18n: true
+---
+
+# /especdev:contrato-ui
+
+## Objetivo
+
+Definir y bloquear los estándares visuales de una feature frontend **antes** de escribir código. Previene el problema más común del desarrollo frontend con IA: inconsistencia visual entre componentes porque no hay un contrato de diseño.
+
+> Adaptado de Get Shit Done (gsd-build/get-shit-done) — UI Design Contracts: "lock visual standards before coding to prevent visually inconsistent AI-generated components."
+
+## Uso
+
+```
+/especdev:contrato-ui                          # Crear contrato para el proyecto
+/especdev:contrato-ui @specs/features/ui/      # Crear para un módulo específico
+/especdev:contrato-ui --desde @figma-export    # Derivar de un export de Figma
+/especdev:contrato-ui --extender               # Extender contrato existente
+```
+
+## Por Qué Existe
+
+| Sin Contrato UI | Con Contrato UI |
+|-----------------|-----------------|
+| Componente A usa `padding: 16px`, B usa `padding: 1rem`, C usa `padding: 20px` | Todos usan `--spacing-md: 1rem` |
+| Cada componente elige sus propios colores | Paleta definida, tokens de diseño |
+| Tipografía inconsistente entre páginas | Escala tipográfica fija |
+| Copywriting variable ("Click here" vs "Continuar" vs "Submit") | Voz y tono definidos |
+| IA genera componentes "bonitos" pero incompatibles entre sí | Todos los componentes siguen el mismo contrato |
+
+## Comportamiento
+
+### Paso 1: Detectar Stack Frontend
+
+```
+Detectando stack frontend...
+├── Framework: React 19 / Next.js 15
+├── Estilos: TailwindCSS 4.x
+├── Componentes: shadcn/ui
+├── Iconos: Lucide Icons
+└── Design system existente: No detectado
+```
+
+### Paso 2: Definir Contrato
+
+El contrato cubre 6 dimensiones:
+
+#### 1. Espaciado (Spacing)
+
+```yaml
+spacing:
+  base: 4px  # Unidad mínima
+  scale:
+    xs: 4px    # 1 unidad
+    sm: 8px    # 2 unidades
+    md: 16px   # 4 unidades (default)
+    lg: 24px   # 6 unidades
+    xl: 32px   # 8 unidades
+    2xl: 48px  # 12 unidades
+  regla: "Todo espaciado DEBE ser múltiplo de 4px"
+```
+
+#### 2. Tipografía (Typography)
+
+```yaml
+typography:
+  familia:
+    primaria: "Inter, system-ui, sans-serif"
+    monospace: "JetBrains Mono, monospace"
+  escala:
+    xs: "0.75rem / 1rem"     # 12px, captions
+    sm: "0.875rem / 1.25rem"  # 14px, labels
+    base: "1rem / 1.5rem"     # 16px, body
+    lg: "1.125rem / 1.75rem"  # 18px, lead
+    xl: "1.25rem / 1.75rem"   # 20px, h4
+    2xl: "1.5rem / 2rem"      # 24px, h3
+    3xl: "1.875rem / 2.25rem" # 30px, h2
+    4xl: "2.25rem / 2.5rem"   # 36px, h1
+  peso:
+    normal: 400
+    medium: 500
+    semibold: 600
+    bold: 700
+```
+
+#### 3. Color (Palette)
+
+```yaml
+color:
+  brand:
+    primary: "#2563EB"      # Acciones principales
+    primary-hover: "#1D4ED8"
+    secondary: "#64748B"     # Acciones secundarias
+  semantic:
+    success: "#16A34A"
+    warning: "#D97706"
+    error: "#DC2626"
+    info: "#2563EB"
+  neutral:
+    background: "#FFFFFF"
+    surface: "#F8FAFC"
+    border: "#E2E8F0"
+    text-primary: "#0F172A"
+    text-secondary: "#64748B"
+    text-muted: "#94A3B8"
+  modo_oscuro: true  # Si aplica, definir variantes
+```
+
+#### 4. Componentes (Patterns)
+
+```yaml
+componentes:
+  botones:
+    primario: "bg-primary text-white rounded-md px-4 py-2 font-medium"
+    secundario: "bg-white border border-border text-secondary rounded-md px-4 py-2"
+    destructivo: "bg-error text-white rounded-md px-4 py-2"
+    fantasma: "text-secondary hover:bg-surface rounded-md px-4 py-2"
+    tamanos: [sm, md, lg]
+  inputs:
+    estilo: "border rounded-md px-3 py-2 focus:ring-2 focus:ring-primary"
+    error: "border-error focus:ring-error"
+    label: "text-sm font-medium text-text-primary mb-1"
+  cards:
+    estilo: "bg-white border rounded-lg p-6 shadow-sm"
+  modales:
+    overlay: "bg-black/50 backdrop-blur-sm"
+    contenido: "bg-white rounded-xl shadow-xl max-w-md mx-auto p-6"
+```
+
+#### 5. Layout
+
+```yaml
+layout:
+  contenedor: "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"
+  grid: "12 columnas"
+  breakpoints:
+    sm: "640px"
+    md: "768px"
+    lg: "1024px"
+    xl: "1280px"
+  sidebar: "w-64 fixed"
+  navbar: "h-16 fixed top-0"
+```
+
+#### 6. Voz y Tono (Copywriting)
+
+```yaml
+copywriting:
+  idioma_ui: "es"  # Del config.yaml
+  voz: "Profesional pero cercano"
+  reglas:
+    - "Usar 'tú' (no 'usted') para el usuario"
+    - "Botones: verbos en infinitivo ('Crear', 'Guardar', 'Cancelar')"
+    - "Errores: explicar qué pasó Y qué hacer ('El email ya existe. Intenta con otro.')"
+    - "Éxito: confirmar la acción completada ('Usuario creado exitosamente')"
+    - "Vacíos: guiar al usuario ('Aún no tienes proyectos. Crea el primero.')"
+  prohibido:
+    - "Click here / Haga clic aquí"
+    - "Error genérico sin contexto"
+    - "Jerga técnica en mensajes al usuario"
+```
+
+### Paso 3: Generar Artefacto
+
+```
+Contrato UI generado:
+  → specs/ui/contrato-ui.yaml (contrato completo)
+  → specs/ui/tokens.css (custom properties generadas)
+```
+
+## Output
+
+### Archivo de Contrato (`specs/ui/contrato-ui.yaml`)
+
+YAML completo con las 6 dimensiones definidas arriba.
+
+### Tokens CSS generados (`specs/ui/tokens.css`)
+
+```css
+:root {
+  /* Spacing */
+  --spacing-xs: 4px;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+  --spacing-xl: 32px;
+
+  /* Colors */
+  --color-primary: #2563EB;
+  --color-primary-hover: #1D4ED8;
+  --color-success: #16A34A;
+  --color-error: #DC2626;
+  --color-text-primary: #0F172A;
+  --color-text-secondary: #64748B;
+  --color-border: #E2E8F0;
+  --color-surface: #F8FAFC;
+
+  /* Typography */
+  --font-primary: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+}
+```
+
+## Integración con Pipeline
+
+```
+/especdev:contrato-ui → contrato-ui.yaml + tokens.css
+  → /especdev:especificar → escenarios referencian tokens
+  → /especdev:planificar-tecnico → plan incluye contrato como dependencia
+  → /especdev:implementar → agente usa tokens, NO inventa estilos
+  → /especdev:revisar → verifica cumplimiento del contrato
+```
+
+## Verificación de Cumplimiento
+
+Durante `/especdev:revisar`, se verifica:
+
+| Verificación | Criterio | Severidad |
+|--------------|----------|-----------|
+| Colores | Solo usa colores del contrato | ❌ Crítico |
+| Espaciado | Múltiplos de la base (4px) | ⚠️ Alto |
+| Tipografía | Solo usa escala definida | ⚠️ Alto |
+| Copywriting | Sigue reglas de voz y tono | ℹ️ Info |
+| Componentes | Usa patterns definidos | ⚠️ Alto |
+| Responsive | Respeta breakpoints | ⚠️ Alto |
+
+## Cuándo Usar
+
+| Situación | Usar contrato |
+|-----------|--------------|
+| Feature con UI nueva | ✅ Sí |
+| Modificación de UI existente | ✅ Sí (extender contrato existente) |
+| API/backend sin UI | ❌ No |
+| Fix de bug visual | ❌ No (contrato ya existe) |
+| Prototipo/POC | ⚠️ Opcional (contrato mínimo) |
+
+## Guardrails
+
+- **Nunca** generar componentes frontend sin contrato UI vigente
+- **Nunca** usar valores hardcoded de color/spacing en código (usar tokens)
+- **Siempre** verificar cumplimiento del contrato en revisión
+- **Siempre** extender (no reemplazar) el contrato cuando se agregan patrones
+- **Siempre** generar tokens CSS/variables junto al contrato

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

@@ -0,0 +1,172 @@
+---
+description: Dividir un blueprint técnico en tareas con TDD (RED→GREEN) y marcadores de paralelismo
+i18n: true
+---
+
+# /especdev:desglosar
+
+## Objetivo
+
+Convertir un blueprint técnico en una lista de tareas ordenadas con enfoque TDD (RED → GREEN → REFACTOR), marcadores de paralelismo `[P]` y fases de ejecución estandarizadas.
+
+> Alineado con spec-kit (github/spec-kit) — formato `[ID] [P?] [Story] Descripción` y 5 fases de ejecución
+
+## Uso
+
+```
+/especdev:desglosar @specs/features/<dominio>/<Feature>.plan.md
+```
+
+## Formato de Tareas
+
+```
+[TID] [P?] [Historia] Descripción
+```
+
+| Campo | Significado | Ejemplo |
+|-------|-------------|---------|
+| `TID` | ID único de tarea | `T001` |
+| `[P]` | Paralelizable (puede ejecutarse en paralelo con otras `[P]` de la misma fase) | `[P]` o vacío |
+| `[Historia]` | Historia de usuario asociada | `[US1]` |
+| Descripción | Qué hacer | Crear modelo de Usuario |
+
+## Output
+
+Genera `specs/features/<dominio>/<Feature>.tasks.md`:
+
+```markdown
+# Tareas: CrearUsuario
+
+**Feature:** usuario/CrearUsuario
+**Plan:** specs/features/usuario/CrearUsuario.plan.md
+**Creado:** 2026-03-21
+
+## Formato: [TID] [P?] [Historia] Descripción
+
+---
+
+## Fase 1: Setup (Paralelizable)
+
+Inicialización del entorno y estructura del proyecto.
+
+- [T001] [P] Setup: Crear estructura de directorios del módulo usuario
+- [T002] [P] Setup: Inicializar configuración de testing
+- [T003] [P] Setup: Configurar Docker compose para tests
+
+---
+
+## Fase 2: Fundación (Secuencial después de Setup)
+
+Infraestructura crítica que el resto del código necesita.
+
+- [T004] [US1] RED: Escribir test para modelo Usuario
+- [T005] [US1] GREEN: Implementar modelo Usuario con validaciones
+  - Archivos: `models/usuario.py`, `tests/unit/test_usuario.py`
+
+- [T006] [US1] RED: Escribir test para UsuarioRepository (crear/buscar)
+- [T007] [US1] GREEN: Implementar UsuarioRepository
+  - Archivos: `repositories/usuario_repo.py`, `tests/unit/test_usuario_repo.py`
+
+---
+
+## Fase 3: Historias de Usuario (Por prioridad)
+
+### P1: Camino Crítico
+
+- [T008] [US1] RED: Test para registro exitoso (happy path)
+- [T009] [US1] RED: Test para email duplicado (sad path)
+- [T010] [US1] GREEN: Implementar UsuarioService.crear()
+  - Archivos: `services/usuario_service.py`, `tests/unit/test_usuario_service.py`
+- [T011] [P] [US1] RED: Test de integración para POST /usuarios
+- [T012] [P] [US1] RED: Test BDD desde escenarios Gherkin P1
+- [T013] [US1] GREEN: Implementar UsuarioController
+  - Archivos: `controllers/usuario_controller.py`, `tests/integration/test_crear_usuario.py`
+
+### P2: Importante
+
+- [T014] [US2] RED: Test para campo obligatorio vacío
+- [T015] [US2] RED: Test para contraseña débil
+- [T016] [US2] GREEN: Implementar validaciones adicionales
+- [T017] [P] [US2] RED: Test BDD desde escenarios Gherkin P2
+
+---
+
+## Fase 4: Polish (Paralelizable)
+
+Refinamientos transversales.
+
+- [T018] [P] Refactor: Extraer validaciones a módulo compartido (si aplica)
+- [T019] [P] Docs: Actualizar API docs con nuevo endpoint
+- [T020] [P] Lint: Ejecutar linter y corregir warnings
+
+---
+
+## Fase 5: Verificación Final
+
+- [T021] Ejecutar suite completa de tests
+- [T022] Verificar coverage ≥ 85% sobre código nuevo
+- [T023] Verificar lint y type-check sin errores
+- [T024] Verificar build exitoso
+
+---
+
+## Orden de Ejecución
+
+```
+Fase 1: T001 ║ T002 ║ T003  (paralelo)
+              ↓
+Fase 2: T004 → T005 → T006 → T007  (secuencial)
+              ↓
+Fase 3: T008 → T009 → T010 → T011 ║ T012 → T013  (mixto)
+         T014 → T015 → T016 → T017  (secuencial)
+              ↓
+Fase 4: T018 ║ T019 ║ T020  (paralelo)
+              ↓
+Fase 5: T021 → T022 → T023 → T024  (secuencial)
+```
+
+**Leyenda:** `→` secuencial | `║` paralelo
+```
+
+## Las 5 Fases de Ejecución
+
+| Fase | Nombre | Tipo | Propósito |
+|------|--------|------|-----------|
+| 1 | **Setup** | Paralelo | Inicialización de entorno y estructura |
+| 2 | **Fundación** | Secuencial | Modelos, repos, infraestructura base |
+| 3 | **Historias de Usuario** | Por prioridad | Features P1 → P2 → P3+ con TDD |
+| 4 | **Polish** | Paralelo | Refactoring, docs, limpieza |
+| 5 | **Verificación Final** | Secuencial | Tests, coverage, lint, build |
+
+## Reglas de Paralelismo
+
+- Tareas marcadas con `[P]` pueden ejecutarse en paralelo con otras `[P]` **de la misma fase**
+- Tareas sin `[P]` son secuenciales y dependen de la tarea anterior
+- **Nunca** ejecutar tareas de fases diferentes en paralelo
+- Las fases 1 y 4 son predominantemente paralelas
+- Las fases 2 y 5 son predominantemente secuenciales
+- La fase 3 es mixta: secuencial dentro de cada historia, potencialmente paralelo entre historias independientes
+
+## Ciclo TDD por Tarea
+
+```
+RED:   Escribir test que FALLA
+       → Ejecutar: verificar que falla por la razón correcta
+
+GREEN: Implementar el código MÍNIMO para que el test pase
+       → Ejecutar: verificar que PASA
+
+REFACTOR: Limpiar sin cambiar comportamiento (solo en Fase 4)
+       → Ejecutar: verificar que sigue pasando
+```
+
+## Puerta de Calidad
+
+Este comando implementa la **Puerta 5 (Preparación de Tareas)**:
+
+- Todas las tareas tienen IDs únicos (`T###`)
+- Todas las tareas de implementación tienen rutas exactas de archivos
+- Tareas paralelizables marcadas con `[P]`
+- Historias asociadas con `[US#]`
+- Las 5 fases están presentes
+- Orden de ejecución documentado

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

@@ -0,0 +1,211 @@
+---
+description: Extraer especificaciones compactas desde código existente (Blueprint Distillation)
+i18n: true
+---
+
+# /especdev:destilar
+
+## Objetivo
+
+Analizar un codebase existente y extraer un **blueprint compacto**: especificaciones, contratos, reglas de negocio y decisiones arquitectónicas implícitas en el código. Es ingeniería inversa de specs, no de arquitectura (para eso existe `/especdev:reversa`).
+
+> Adaptado de DeepCode (HKUDS/DeepCode) — Blueprint Distillation: "comprimir código fuente para extraer especificaciones esenciales, filtrando ruido y preservando patrones críticos."
+
+## Uso
+
+```
+/especdev:destilar                             # Destilar el proyecto actual
+/especdev:destilar @ruta/al/modulo             # Destilar un módulo específico
+/especdev:destilar --formato gherkin           # Output en formato Gherkin
+/especdev:destilar --formato resumen           # Output como resumen ejecutivo
+/especdev:destilar --formato contratos         # Solo interfaces y contratos
+```
+
+## Por Qué Existe
+
+| Situación | Sin Destilar | Con Destilar |
+|-----------|-------------|--------------|
+| Proyecto heredado sin docs | Leer todo el código | Blueprint de 200 líneas |
+| Migración a nueva versión | Riesgo de perder reglas implícitas | Spec explícita para validar |
+| Onboarding de nuevo dev | Semanas entendiendo el código | Blueprint + mapa en 1 hora |
+| Rewrite parcial | ¿Qué comportamiento preservar? | Contratos explícitos |
+
+## Diferencia con `/especdev:reversa`
+
+| Aspecto | `/especdev:reversa` | `/especdev:destilar` |
+|---------|--------------------|--------------------|
+| **Foco** | Arquitectura (componentes, conexiones) | Comportamiento (reglas, contratos) |
+| **Output** | Mapa de componentes | Especificaciones compactas |
+| **Pregunta** | "¿Cómo está construido?" | "¿Qué hace y por qué?" |
+| **Formato** | Diagrama + tabla | Gherkin / contratos / resumen |
+
+Se complementan: `reversa` te da el **mapa**, `destilar` te da las **reglas**.
+
+## Comportamiento
+
+### Paso 1: Análisis de Superficie
+
+```
+Escaneando módulo src/services/payment/...
+├── 8 archivos, 1,247 líneas de código
+├── 23 funciones exportadas
+├── 4 interfaces/tipos públicos
+├── 12 tests encontrados
+└── 3 dependencias externas (Stripe, Redis, Logger)
+```
+
+### Paso 2: Extracción de Reglas de Negocio
+
+El destilador busca reglas implícitas en:
+
+| Fuente | Qué Extrae | Ejemplo |
+|--------|-----------|---------|
+| **Validaciones** | Reglas de dominio | "Monto mínimo: $1.00, máximo: $999,999" |
+| **Condicionales** | Lógica de negocio | "Si el usuario es premium, no cobra comisión" |
+| **Error handling** | Casos límite | "Reintentar 3 veces si Stripe devuelve 429" |
+| **Tests** | Comportamiento esperado | "Webhook debe ser idempotente" |
+| **Tipos/Interfaces** | Contratos | "PaymentIntent requiere: amount, currency, customerId" |
+| **Comentarios** | Intención del dev original | "// HACK: Stripe no soporta ARS, convertir a USD" |
+
+### Paso 3: Compresión
+
+Eliminar ruido, preservar esencia:
+
+```
+Código original: 1,247 líneas
+├── Boilerplate eliminado: 400 líneas (imports, exports, logging)
+├── Implementación interna eliminada: 500 líneas
+├── Duplicación eliminada: 100 líneas
+└── Blueprint resultante: ~247 líneas (ratio 5:1)
+```
+
+**Regla de compresión:** El blueprint debe ser ≤20% del código original.
+
+### Paso 4: Formato de Output
+
+#### Formato Gherkin (default)
+
+```gherkin
+Feature: Procesamiento de Pagos
+  El sistema procesa pagos a través de Stripe
+  con reintentos automáticos y manejo de moneda.
+
+  Reglas de Negocio:
+  - Monto mínimo: $1.00 USD
+  - Monto máximo: $999,999.00 USD
+  - Monedas soportadas: USD, EUR, BRL
+  - Usuarios premium: sin comisión de procesamiento
+  - Comisión estándar: 2.9% + $0.30
+
+  Escenario: Pago exitoso
+    Dado un usuario con customerId válido en Stripe
+    Y un monto de $50.00 USD
+    Cuando se procesa el pago
+    Entonces se crea un PaymentIntent en Stripe
+    Y se registra la transacción en la base de datos
+    Y se emite el evento "payment.completed"
+
+  Escenario: Reintento por rate limit
+    Dado que Stripe responde con HTTP 429
+    Cuando se procesa el pago
+    Entonces se reintenta hasta 3 veces con backoff exponencial
+    Y si todos fallan, se marca como "payment.failed"
+    Y se notifica al equipo de soporte
+
+  Escenario: Moneda no soportada
+    Dado un monto en ARS (peso argentino)
+    Cuando se procesa el pago
+    Entonces se convierte a USD usando el tipo de cambio del día
+    Y se procesa en USD
+    Y se registra el tipo de cambio usado
+```
+
+#### Formato Contratos
+
+```typescript
+// Blueprint: Contratos del Módulo de Pagos
+// Extraído de: src/services/payment/ (8 archivos, 1,247 LOC)
+// Fecha: 2026-03-21
+
+interface PaymentIntent {
+  amount: number;        // centavos, min: 100, max: 99999900
+  currency: 'USD' | 'EUR' | 'BRL';
+  customerId: string;    // Stripe customer ID
+  metadata?: Record<string, string>;
+}
+
+interface PaymentResult {
+  id: string;
+  status: 'succeeded' | 'failed' | 'pending';
+  stripePaymentIntentId: string;
+  amount: number;
+  fee: number;           // 0 para premium, 2.9% + 30 para estándar
+  createdAt: Date;
+}
+
+// Contratos de servicio
+type ProcessPayment = (intent: PaymentIntent) => Promise<PaymentResult>;
+type RefundPayment = (paymentId: string, amount?: number) => Promise<RefundResult>;
+type GetPaymentStatus = (paymentId: string) => Promise<PaymentResult>;
+
+// Invariantes
+// - ProcessPayment es idempotente (mismo intent = mismo resultado)
+// - RefundPayment parcial: amount <= payment.amount
+// - Retry policy: 3 intentos, backoff exponencial (1s, 2s, 4s)
+```
+
+#### Formato Resumen
+
+```markdown
+## Blueprint: Módulo de Pagos
+
+### Responsabilidad
+Procesar pagos a través de Stripe con reintentos y conversión de moneda.
+
+### Reglas de Negocio
+1. Montos: $1.00 - $999,999.00 USD
+2. Monedas: USD, EUR, BRL (ARS se convierte a USD)
+3. Comisión: 2.9% + $0.30 (premium: 0%)
+4. Reintentos: 3x con backoff exponencial ante rate limit
+5. Idempotencia: mismo PaymentIntent = mismo resultado
+
+### Dependencias Externas
+- Stripe API v3 (pagos, reembolsos)
+- Redis (cache de tipos de cambio, idempotency keys)
+
+### Riesgos Identificados
+- Conversión ARS→USD usa hack manual (comentario en código)
+- No hay circuit breaker para Stripe
+- Tests no cubren reembolsos parciales
+```
+
+## Integración con Pipeline
+
+```
+/especdev:destilar → blueprint
+  → /especdev:especificar → .feature (informada por blueprint)
+  → /especdev:clarificar → validar contra blueprint
+  → /especdev:planificar-tecnico → usar contratos como base
+```
+
+El blueprint alimenta el pipeline de specs, cerrando el ciclo:
+**Código existente → Blueprint → Spec → Nuevo código validado**
+
+## Almacenamiento
+
+El blueprint se guarda en:
+
+```
+.especdev/blueprints/
+├── payment.blueprint.md      # Blueprint del módulo de pagos
+├── auth.blueprint.md         # Blueprint del módulo de auth
+└── _index.md                 # Índice de blueprints
+```
+
+## Guardrails
+
+- **Nunca** incluir credenciales o secretos en el blueprint
+- **Nunca** exceder 20% del tamaño del código original
+- **Siempre** indicar qué archivos se analizaron
+- **Siempre** marcar los "hacks" o workarounds encontrados como riesgos
+- **Siempre** distinguir entre reglas de negocio confirmadas (por tests) y supuestas (por código)

package/scripts/.claude/commands/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 |