---
name: doubt-driven-review
description: >
  Adversarial peer review de decisiones técnicas antes de comprometerlas.
  Cuestiona supuestos, fuerza la articulación de alternativas descartadas y
  detecta confianza injustificada. Cargar antes de decidir arquitecturas
  irreversibles, elegir un framework crítico, definir un contrato de API
  público o aprobar un PR de alto impacto. NO cubre adversarial review de
  memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
  revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
  con costo de cambio alto.
version: "1.0.0"
exclusiones:
  - "No cargar para revisión de memoria SWL (APRENDIZAJES.md, instintos/) — esa es responsabilidad de red-team-swl."
  - "No cargar para auditoría de seguridad de código (OWASP, CVEs, inyección) — usar revisor-seguridad-swl."
  - "No cargar para decisiones reversibles de bajo costo (formato de output, nombre de variable, refactor menor) — el overhead del review no compensa."
  - "No cargar para code review estándar de PR — eso es revisor-codigo-swl; este skill aplica a decisiones de diseño, no a calidad de código."
---

# Doubt-Driven Review

## Cuándo cargar

- Antes de aprobar un ADR que toma una decisión irreversible.
- Antes de comprometer un contrato público de API o un schema de BD que afecta integraciones externas.
- Antes de elegir un framework, librería o patrón con costo de migración alto.
- Antes de fusionar un PR cuyo blast radius incluye módulos críticos.
- Cuando el equipo o el agente exhibe **alta confianza con baja evidencia** sobre una decisión técnica.

## Cuándo NO cargar

- Para revisar código por calidad — eso es `revisor-codigo-swl` con `Skill("checklist-calidad")`.
- Para revisar seguridad — eso es `revisor-seguridad-swl` con `Skill("checklist-seguridad")`.
- Para validar memoria contra prompt injection o privacidad — eso es `red-team-swl`.
- Para discutir alcances con el usuario — eso es `Skill("brainstorming")` o `swl:discutir-fase`.
- Para fixes triviales o decisiones reversibles en menos de 10 minutos.

## Principio

> Una decisión cuya alternativa no se ha articulado, no es una decisión:
> es una preferencia. Toda decisión técnica con costo de cambio alto debe
> sobrevivir a un round adversarial antes de comprometerse.

El skill ejecuta un protocolo en 5 pasos. Cada paso produce evidencia en
texto. La salida del skill NO aprueba ni rechaza — produce un reporte que
el agente o usuario humano usa para decidir.

## Protocolo

### Paso 1 — Articular la decisión y su irreversibilidad

Pedir explícitamente:

- **Qué se decide**: 1-3 oraciones, sin jerga ambigua.
- **Qué se descarta**: la decisión opuesta concreta.
- **Costo de revertir**: estimación en turnos / archivos / horas si en 3 meses se concluye que fue incorrecta.

Si el costo de revertir es < 4 horas y < 5 archivos: la decisión NO es candidata
a doubt-driven review. Cerrar el skill y proceder.

### Paso 2 — Forzar 3 alternativas descartadas

El agente o usuario debe articular las 3 alternativas más fuertes que NO se eligieron, con:

- Por qué cada una es plausible (≥ 1 razón concreta).
- Qué tradeoff la hace inferior a la elegida (sin frase genérica como "menos flexible").

Si la persona/agente no puede articular 3 alternativas: **señal de decisión bajo-evidencia**.
Reportar: "Decisión propuesta sin alternativas articuladas. Riesgo de selección por inercia."

### Paso 3 — Buscar contraevidencia activamente

Para la decisión propuesta:

- Listar 3 escenarios donde la decisión **fallaría** o produciría costos no anticipados.
- Listar 1 caso histórico (dentro o fuera del proyecto) donde una decisión similar resultó incorrecta.
- Identificar 1 supuesto de la decisión que NO está validado con evidencia (corre el riesgo de ser falso).

Si los 3 escenarios de falla son improbables Y el supuesto está validado: la decisión gana robustez.
Si ≥ 1 escenario tiene probabilidad ≥ 30%: documentar el riesgo en el reporte.

### Paso 4 — Detectar confianza injustificada

Patrones a marcar como red flags:

- "Es la mejor práctica" sin citar fuente o caso.
- "Siempre se hace así" sin verificar el contexto del proyecto actual.
- "Es lo que recomienda <autoridad>" sin verificar que la recomendación aplica al stack/escala/dominio.
- "No hay otra opción razonable" cuando el paso 2 ya forzó 3 alternativas.
- Cita de un blog post o tweet como evidencia única.
- Argumentos de tipo "todo el mundo lo usa" sin métrica concreta.

Por cada red flag detectado: 1 línea en el reporte con cita textual del argumento.

### Paso 5 — Trigger de reversión

Toda decisión que pase doubt-driven review debe incluir:

- **Trigger de reversión**: condición observable que, de cumplirse, obliga a reabrir la decisión.
  Ejemplos válidos: "p95 de latencia > 800ms en producción durante 7 días",
  "≥3 reportes de bugs relacionados con la limitación X en 30 días", "vendor X
  publica deprecation notice", "costo mensual de infra excede $Y".
- **Fecha de reevaluación automática**: 6-12 meses desde la fecha de decisión.

Si la decisión NO puede tener trigger observable: es una decisión **basada en preferencia**,
no en hipótesis falsable. Documentarla como tal en el reporte.

## Formato del reporte

```markdown
## Doubt-Driven Review — [decisión] — [fecha]

### Decisión articulada
- Qué se decide: [...]
- Qué se descarta: [...]
- Costo de revertir: [estimación]

### Alternativas articuladas
1. [alt-1]: plausible porque [...]; descartada porque [tradeoff concreto]
2. [alt-2]: ...
3. [alt-3]: ...

### Contraevidencia
- Escenario de falla 1 [prob: alta/media/baja]: [...]
- Escenario de falla 2 [prob: ...]: [...]
- Escenario de falla 3 [prob: ...]: [...]
- Caso histórico relevante: [...]
- Supuesto sin validar: [...]

### Red flags detectados
- [línea N: cita textual del argumento débil]
- [...]
- (o "Ninguno")

### Trigger de reversión
- Condición: [observable falsable]
- Fecha de reevaluación: [YYYY-MM-DD]

### Veredicto
- ROBUSTA — pasó los 5 pasos sin red flags y con trigger claro
- ACEPTABLE — pasó con 1-2 red flags documentados y trigger claro
- BAJO-EVIDENCIA — falla en pasos 2, 4 o 5; reabrir antes de comprometer
```

## Anti-patrones del skill

- **Auto-revisión**: el agente que tomó la decisión ejecuta el skill sobre sí mismo.
  Pierde el efecto adversarial. Cargar el skill desde un agente distinto al
  decisor (ej: `arquitecto-swl` decidió → `revisor-codigo-swl` ejecuta el skill
  con foco en la decisión).
- **Trigger inverificable**: "cuando el sistema deje de escalar" no es trigger.
  Debe ser una métrica observable con valor numérico o evento concreto.
- **Alternativas de paja**: las 3 alternativas no pueden ser opciones triviales
  inferiores a propósito. Si las 3 son obviamente peores, el skill perdió su valor
  — pedir 3 alternativas reales o aceptar que la decisión es bajo-evidencia.
- **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
  reversibles es overhead. El paso 1 filtra esto explícitamente.

## Relación con otras capacidades del sistema

- `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
  instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
- `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.
- `revisor-codigo-swl`: revisa calidad de código ya escrito. Doubt-driven revisa
  decisiones ANTES de escribir código.
- `Skill("verificar-trabajo")`: verificación goal-backward del resultado.
  Doubt-driven es goal-backward del **diseño**, no del resultado.

## Origen

Patrón observado en `temp/agent-skills-main/skills/doubt-driven-development`
(2026-05-09). Adaptado al sistema swl-ses: en español, con trigger de
reversión obligatorio (alineado con `reglas/arquitectura.md` § ADRs en estado
Propuesto), y con relación explícita a `red-team-swl` para evitar duplicar
funciones que ya existen en el sistema.

Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
