---
name: protocolo-revision-swl
description: >
  Protocolo de revisión adversarial per-task con git diff como single source of
  truth. Adapta el patrón task-local review de cc-sdd al ecosistema SWL: los
  revisores existentes (revisor-codigo-swl, revisor-seguridad-swl, revisor-*-swl)
  aplican este protocolo cuando trabajan sobre una sola tarea atómica en lugar
  de una fase completa. Devuelve APPROVED o REJECTED con findings de severidad
  estructurados y boundary checks. Cargar desde el agente revisor cuando
  ejecutar-fase corre en modo --iterative (task por task) o cuando se solicita
  revisión acotada a un commit / patch específico.
version: "1.0.1"
evolved: true
evolved-from: "1.0.0"
evolved-at: "2026-05-16"
evolved-by: "aprender"
evolved-note: "v1.0.1: sección 'Validación de afirmaciones de existencia/no-existencia' formaliza regla `verificar-citas-normativas § Familia 2` aplicada a revisores. Origen: 2 falsos positivos del revisor externo en PR #28 v1.5.2."
herramientasPermitidas: [Read, Grep, Glob, Bash]
exclusiones:
  - "No cargar para revisión de fase completa multi-archivo — usar el flujo estándar del revisor con `/swl:revisar` y `/swl:verificar`."
  - "No cargar para auditoría de seguridad profunda — usar `revisor-seguridad-swl` con `checklist-seguridad`."
  - "No cargar como sustituto de la verificación goal-backward post-ejecución — `verificar-trabajo` cubre eso a nivel de fase."
  - "No cargar para revisar código que no ha sido staged ni commiteado todavía — el protocolo requiere un diff o set de archivos definido."
evolvable: true
---

# Protocolo de revisión per-task

## Propósito

Revisar el resultado de UNA tarea atómica de implementación (no una fase
completa) con el rigor de un revisor adversarial. El protocolo está diseñado
para coexistir con los revisores especializados existentes (`revisor-codigo-swl`,
`revisor-react-swl`, `revisor-typescript-swl`, etc.): esos agentes cargan
este skill cuando el alcance es task-local en lugar de phase-wide.

Adaptado del patrón `kiro-review` de cc-sdd. Mantiene los principios de
swl-ses (separación revisor/ejecutor de `reglas/gobernanza.md`, veto items
y cap enforcement, scoring 9.0+ obligatorio para APPROVED).

## Cuándo cargar

- El orquestador ejecuta `/swl:ejecutar-fase --iterative` y necesita revisión task-por-task
- Un agente implementador reportó `READY_FOR_REVIEW` para una sub-tarea específica
- El usuario pide "revisa este último commit" o "revisa lo que acabo de hacer"
- Tras una remediación de un finding previo y se necesita re-verificación acotada

## Cuándo NO cargar

Ver `exclusiones` en frontmatter.

---

## Inputs requeridos

Antes de empezar, identifica los siguientes inputs. Si falta cualquiera, pide
clarificación al caller (orquestador o implementador) en lugar de proceder
con asunciones.

| Input | Forma | Obligatorio |
|-------|-------|-------------|
| Task ID | Texto de la tarea desde PLAN.md (ej. "3.2 — Crear endpoint POST /facturas") | Sí |
| Boundary scope | Lista de paths/módulos que la tarea puede modificar | Sí |
| Spec references | IDs de requirements y design sections que la tarea satisface | Sí — si existen |
| Diff | `git diff <base>..HEAD` o set de archivos modificados | Sí |
| Validation commands | Comandos descubiertos por el caller (test, build, lint, smoke) | Sí — si aplica el stack |
| Implementer status report | El reporte estructurado del ejecutor (`READY_FOR_REVIEW`, archivos tocados, decisiones) | Recomendado |

---

## Paso 1 — Primera acción obligatoria: `git diff`

Antes de leer cualquier otro archivo, ejecuta:

```bash
git diff --stat       # alcance del cambio
git diff <base>..HEAD # contenido real
```

El reporte del implementador NO es fuente de verdad. El diff sí. Si el diff
es grande, lee los archivos modificados directamente — no resuamen ni inferas
desde el reporte del ejecutor.

**Por qué**: el implementador puede honestamente reportar "implementé X" pero
haber introducido Y como efecto colateral. El diff captura todo, incluido lo
que el ejecutor no recuerda haber tocado.

---

## Paso 2 — Checks mecánicos (resultado = señal primaria)

Estos checks son determinísticos y producen evidencia directa. Aplica TODOS
antes de pasar a interpretación.

### Check 1: Regression safety

Corre la suite de tests del proyecto con las `validation_commands` provistas.
Ejemplo:

```bash
npm test               # o pytest, o cargo test, etc.
```

- **Tests pasan** → continuar.
- **Tests fallan** → `REJECTED` inmediato. Incluye el conteo y nombres de tests fallidos en el reporte.
- **Tests skipped aumentan vs base** → riesgo de regresión silenciosa (regla `monitor-ci.md`). Reportar el delta como finding de severidad MAJOR.

### Check 2: Sin marcadores placeholder nuevos

```bash
git diff <base>..HEAD | grep -E "\+.*\b(TBD|TODO|FIXME|HACK|XXX)\b" || true
```

Marcadores nuevos solo se aceptan con justificación explícita en el reporte
del implementador asociada al PLAN.md vigente (referencia a task ID, no texto suelto).
Sin justificación → finding MAYOR.

### Check 3: Sin secretos hardcodeados

```bash
git diff <base>..HEAD | grep -E "(api[_-]?key|password|secret|token)\s*[=:]\s*[\"'][^\"'\s]{8,}[\"']" -i || true
```

Cualquier match → `REJECTED` con finding CRÍTICO. Aplica los patrones
documentados en `reglas/seguridad-agentes.md` § "Protección de secretos".

### Check 4: Boundary violations

Lista de archivos modificados:

```bash
git diff --name-only <base>..HEAD
```

Cada archivo modificado DEBE estar dentro del `boundary scope` declarado en
la tarea. Si un archivo fuera del boundary aparece modificado:

- Si es modificación trivial (formateo, comentario) → finding MENOR.
- Si es modificación funcional → finding MAYOR. La tarea debe declarar el
  boundary extendido o el cambio se devuelve al implementador para extraer
  a una tarea aparte.

---

## Paso 3 — Verificación de alineación con spec

Lee directamente:

- El texto de la tarea en `PLAN.md` (no parafrases — copia literal).
- Los requirements citados en el campo `requirements` de la tarea.
- Las secciones de design citadas si existen.

Para cada requirement/design ref, verifica:

| Pregunta | Cómo verificar |
|----------|----------------|
| ¿El código implementa lo que el requirement dice? | Mapear líneas concretas del diff al texto del requirement |
| ¿Falta algo del requirement que el código no cubre? | Listar gaps específicos |
| ¿Hay código fuera del scope del requirement? | Comparar con design — si no está justificado, es scope creep |

Si hay gap de cobertura → finding MAYOR con cita del requirement y línea
faltante en el diff.

---

## Paso 4 — Veto items (heredados del revisor base)

Los revisores SWL existentes declaran sus propios veto items (ver
`reglas/gobernanza.md` § "Veto items y cap enforcement"). Cuando este
protocolo se carga desde uno de ellos, los veto items del revisor padre
aplican íntegros.

**Si detectas CUALQUIER veto item**:

- Score CAP automático a 6.0/10.
- Verdict pasa a `REJECTED` independientemente de qué tan limpio esté el resto.
- 2+ veto items → cap a 3.0/10.

Lista de veto items del revisor padre debe estar disponible en su SKILL/agente.
Si no se puede determinar, reporta `MANUAL_VERIFY_REQUIRED` en lugar de inventar.

---

## Paso 5 — Emitir veredicto estructurado

### Formato del reporte

```json
{
  "protocol": "protocolo-revision-swl",
  "task_id": "3.2 — Crear endpoint POST /facturas",
  "verdict": "APPROVED | REJECTED",
  "score": 9.2,
  "score_cap_applied": null,
  "mechanical_checks": {
    "regression_safety": "PASS",
    "no_new_placeholders": "PASS",
    "no_hardcoded_secrets": "PASS",
    "boundary_respected": "PASS | VIOLATIONS_FOUND"
  },
  "spec_alignment": {
    "requirements_covered": ["R-12", "R-13"],
    "requirements_gap": [],
    "design_drift": "NONE | SLIGHT | SIGNIFICANT"
  },
  "veto_items": [],
  "findings": [
    {
      "severity": "CRITICAL | MAJOR | MINOR",
      "file": "app/api/facturas.py:42",
      "issue": "Descripción breve",
      "remediation": "Qué cambiar y cómo"
    }
  ],
  "summary": "Una oración resumiendo el veredicto y la razón principal.",
  "next_action": "MERGE | FIX_AND_RE_REVIEW | ESCALATE_TO_HUMAN"
}
```

### Reglas de scoring (compatibles con `checklist-calidad`)

- `APPROVED` requiere `score >= 9.0` Y `veto_items.length === 0` Y todos los
  mechanical_checks en PASS.
- Severidad MAJOR baja el score 1.0 punto cada una.
- Severidad MINOR baja 0.3 puntos cada una.
- Severidad CRITICAL → automaticamente `REJECTED` (score irrelevante).
- 1 veto item → cap a 6.0. 2+ veto items → cap a 3.0.

### Reglas del `next_action`

- `MERGE`: APPROVED — el caller (orquestador) puede commitear y avanzar a la siguiente tarea.
- `FIX_AND_RE_REVIEW`: REJECTED con findings MAYORES — el implementador aplica remediation, se vuelve a invocar este protocolo. Máximo 2 ciclos antes de escalar.
- `ESCALATE_TO_HUMAN`: 2 ciclos de FIX no convergieron, O hay CRÍTICO sin remediación clara, O hay decisión de scope ambigua. Activa el `notificador-swl` si está configurado.

---

## Persistencia del veredicto

El veredicto JSON se persiste en:

```
.planning/audit/reviews/<task-id>-<timestamp>.json
```

Esto permite que `auto-evolucion-swl` y `/swl:metricas` calculen tasas de
APPROVED vs REJECTED por agente revisor y por tipo de tarea — datos
necesarios para identificar revisores con calibración floja o tipos de
tarea sistemáticamente problemáticos.

---

## Gotchas / Errores comunes no obvios

- **Confiar en el reporte del implementador como source of truth**: el primer paso obligatorio es `git diff`. Saltarse esto y derivar el veredicto del status report del implementador deja pasar bugs colaterales no reportados. Causa: optimización falsa para ahorrar tokens. Solución: `git diff --stat` siempre antes de cualquier interpretación.
- **Boundary violation reportada como MENOR sin verificar funcionalidad**: el revisor ve que se modificó un archivo fuera del boundary y lo marca MENOR porque "se ve pequeño". Causa: no se inspeccionó qué hace el cambio. Solución: para CUALQUIER archivo fuera del boundary, abrir el cambio y clasificar trivial vs funcional antes de asignar severidad.
- **Tests skipped tratados como tests pasados**: el conteo de tests verde no distingue entre pasados y saltados. Causa: parsing superficial del output del runner. Solución: comparar `skipped` count vs base — si aumenta sin causa documentada en el diff, es regresión silenciosa (regla `monitor-ci.md`).
- **APPROVED con score < 9.0 "porque la tarea era pequeña"**: el revisor reduce el umbral subjetivamente. Causa: ceder a presión de entrega. Solución: la regla es 9.0 estricto; tareas pequeñas que no llegan a 9.0 indican findings que valen MENOR o MAYOR — emitir como findings y devolver al implementador.
- **Veto items ignorados porque "el resto está limpio"**: el cap de score es no-negociable. Causa: el revisor pondera "promedio" de calidad. Solución: 1 veto item = score capped automáticamente, sin compensación posible desde otras dimensiones.

---

## Validación de afirmaciones de existencia / no-existencia

Anti-patrón recurrente observado en revisores externos (sesión swl-ses
2026-05-16): el revisor emite findings del tipo *"X no existe en Y"* o
*"X no está registrado en Z"* basados en context incompleto del propio
revisor (vio un archivo del repo pero no verificó el filesystem actual
tras los últimos cambios). Casos documentados:

1. *"Two new skills were added but are not listed in plugin.json"* —
   verificado con `grep -n "nemesis-evaluacion-json" plugin.json`: SÍ
   estaban listados (líneas 107-108). Falso positivo.
2. *"The skill `nemesis-redistribuir` doesn't exist in the habilidades/
   directory"* — verificado con `ls habilidades/nemesis-redistribuir/`:
   12,640 bytes presentes. Falso positivo.

### Regla

Antes de emitir un finding del tipo "X no existe / X no está registrado / X
está ausente", el revisor DEBE verificar con `Read`, `Grep` o `ls` directo
sobre el filesystem actual. Una afirmación de no-existencia sin verificación
es **propagación de cita ajena**, prohibida por la regla global del usuario
`verificar-citas-normativas.md § Familia 2` (citas archivo:línea en reportes
de auditoría).

### Protocolo de verificación obligatorio

| Afirmación | Comando de verificación mínimo |
|---|---|
| "X no existe en el directorio Y/" | `ls Y/X` o `find Y -name "X*"` |
| "X no está registrado en plugin.json" | `grep -n "X" plugin.json` |
| "X no está en manifiestos/modulos.json" | `grep -n "X" manifiestos/modulos.json` |
| "El archivo Z no tiene la sección W" | `Read` del archivo + buscar W |
| "El path A no resuelve a B" | `node -e "console.log(require('path').resolve('A'))"` o equivalente |

Si el comando confirma la afirmación → emitir finding válido.
Si el comando contradice la afirmación → **descartar como falso positivo** y
no emitirlo. Si el revisor lo emite igual, queda como ruido que el equipo
debe filtrar manualmente — degrada confianza en futuros findings.

### Pattern correcto del finding

```
## [SEVERIDAD] Título

**Verificación**: `grep -n "nemesis-redistribuir" plugin.json`
**Resultado**: 0 ocurrencias (línea 108 esperada por habilidades/nemesis-redistribuir/ en disco).
**Causa**: skill creado pero no registrado en plugin.json.
**Fix**: agregar `"habilidades/nemesis-redistribuir"` en el array `skills`.
```

El finding cita el comando ejecutado y su output. El reviewer humano puede
re-ejecutarlo para validar. Sin esta evidencia, el finding es opaco.

### Anti-patrón explícito

NO emitir findings de no-existencia derivados de "leí el ADR/contexto y
asumo que X no existe porque no se menciona". El ADR documenta una
DECISIÓN; el filesystem documenta el ESTADO. Son ortogonales.

### Origen

Detectado en sesión 2026-05-16 (swl-ses): revisor externo emitió 2 findings
de no-existencia (skills no listados) que fueron falsos positivos. La regla
extendida `verificar-citas-normativas.md § Familia 2` los descartó al
verificar con `ls`/`grep` directos. Esta sección formaliza la regla a nivel
de skill para que aplique automáticamente al cargarlo.

---

## Relación con otros componentes SWL

| Componente | Relación |
|-----------|----------|
| `revisor-codigo-swl` y revisores de lenguaje | Cargan este skill cuando trabajan task-local en lugar de phase-wide |
| `ejecutar-task-iterativo` (Sub-fase 4) | Invoca este protocolo después de cada implementer dispatch en modo `--iterative` |
| `verificar-trabajo` | Complementario — verificar-trabajo es goal-backward post-fase; este protocolo es task-local post-implementación |
| `reglas/gobernanza.md` | Veto items + cap enforcement heredados |
| `checklist-calidad` | Score >=9.0 unificado |
| `auto-evolucion-swl` | Consume los veredictos persistidos para detectar revisores descalibrados |

## Checklist de cierre del protocolo

- [ ] `git diff --stat` ejecutado y diff leído antes de cualquier interpretación
- [ ] 4 mechanical checks ejecutados (regression, placeholders, secretos, boundary)
- [ ] Alineación con spec verificada citando IDs concretos
- [ ] Veto items del revisor padre evaluados
- [ ] Score calculado y cap aplicado si corresponde
- [ ] Veredicto JSON persistido en `.planning/audit/reviews/`
- [ ] `next_action` claro (MERGE / FIX_AND_RE_REVIEW / ESCALATE_TO_HUMAN)
