---
paths:
  - "**/agentes/*.md"
---
# Regla: Intent Engineering para agentes ALTO riesgo

Esta regla es **OBLIGATORIA** y aplica al crear, modificar o promover agentes
del sistema SWL cuyo `nivelRiesgo` sea `ALTO`. Implementa el framework
"Intent Engineering" de 8 partes de Pawel Huryn (*Lead Agents Like Humans*,
Product Compass, 2026-05).

---

## Principio

> Un agente con autonomía elevada que opera sin intent specification explícito
> falla silenciosamente por instrucciones ambiguas, deriva de scope o pérdida
> de health metrics. Los agentes ALTO riesgo del sistema SWL DEBEN declarar
> las 8 partes del framework de forma verificable (frontmatter + fragmento),
> no implícita.

Huryn lo resume:

> "Agents don't fail because the model is weak. They fail because intent is
> incomplete. Objectives are vague. Outcomes are implicit. Trade-offs are
> unstated. Constraints are treated as suggestions. Autonomy is granted
> without understanding risk." (Lead Agents Like Humans, línea 56)

SWL adopta el framework parcialmente: las partes 5 (Org Context) y 3
(Desired Outcomes) viven en `CLAUDE.md` y `PLAN.md` respectivamente, no en
cada agente. Las otras 6 son responsabilidad del autor del agente.

---

## Cuándo aplicar

OBLIGATORIO al:

- Crear un agente nuevo `nivelRiesgo: ALTO`.
- Modificar el frontmatter de un agente `nivelRiesgo: ALTO` existente.
- Promover un agente de `MEDIO` o `BAJO` a `ALTO`.
- Auditar agentes con `/swl:revisar` cuando se detecta deriva de scope.

NO aplicar al:

- Agentes `BAJO` o `MEDIO` riesgo (los campos son opcionales para ellos).
- Cambios cosméticos al cuerpo markdown del agente sin tocar frontmatter.
- Skills, hooks, comandos (la regla aplica solo a agentes).

---

## Lo que DEBE declarar un agente ALTO

### En el frontmatter YAML

```yaml
nivelRiesgo: ALTO            # Parte 7 — Autonomy Boundaries
maxTurnos: <int>             # Parte 8 — Stop Rules (cap iteraciones)
strategy: "<1-3 lineas>"     # Parte 1 — Strategy (max 500 chars)
healthMetrics:               # Parte 4 — qué NO debe degradar
  - "<invariante 1>"
  - "<invariante 2>"
steering:                    # Parte 6 — prompt-level constraints
  - "<guía de comportamiento o @reglas/X.md>"
hardGuardrails:              # Parte 6 — orchestration-level constraints
  - "<restricción enforced por hook/schema o @reglas/X.md>"
fragmentos:
  - _intent-spec             # Importa el bloque compartido al system prompt
```

### En el cuerpo markdown

NO requerido pero recomendado: agregar sección breve "Health Metrics" o
"Constraints" si el rol del agente justifica explicación adicional.

---

## Criterios de calidad por campo

### `strategy:`

- 1-3 líneas, máximo 500 caracteres.
- Nombra el tradeoff que el agente prioriza.
- NO es boilerplate genérico ("código limpio", "buenas prácticas").
- Hereda del proyecto cuando aplica; declara explícito cuando el rol impone
  tradeoffs propios.

**Ejemplo válido** (`migrador-swl`):
```yaml
strategy: >
  Preservar integridad de datos por encima de velocidad de migración.
  Expand-contract obligatorio sobre cambios destructivos. Rollback siempre
  viable. Sin downtime es preferible a migración rápida.
```

**Ejemplo inválido**:
```yaml
strategy: "Migrar datos de forma segura."   # boilerplate genérico
```

### `healthMetrics:`

- Lista de invariantes blandas que el agente protege mientras trabaja.
- Distintas de `outcomes`: outcomes se persiguen, health metrics se
  protegen.
- Sin métrica = sin protección. Agentes ALTO sin health metrics violan
  Goodhart's Law por construcción.
- Pueden ser cualitativas si no hay telemetría que las mida live ("sin
  warnings nuevos de ORM").

### `steering:`

- Soft constraints. El agente las lee como guía.
- Acepta texto inline o referencia a regla global (`@reglas/X.md`).
- NO duplicar contenido de `@reglas/X.md` — referenciar evita drift.

### `hardGuardrails:`

- Hard constraints aplicadas por arquitectura (hooks, schemas, sandbox).
- Cada item DEBE referenciar el mecanismo que enforza:
  - `@reglas/seguridad-agentes.md § Privilegio mínimo` (regla global)
  - `@hooks/proteccion-rutas.js` (hook bloqueante)
  - `@schemas/agent-frontmatter.schema.json#properties.tools` (validación)
- Si la restricción no tiene mecanismo de enforcement, NO es hard
  guardrail — es steering.

---

## Excepciones legítimas

NO aplica la regla cuando:

1. **El agente acaba de bajar de ALTO a MEDIO/BAJO**: si en una revisión se
   determina que un agente puede operar con menos privilegio, primero baja
   el `nivelRiesgo`, luego los campos se vuelven opcionales.

2. **El agente está en proceso de deprecación**: agentes marcados
   `evolvable: false` con plan de retiro documentado en ADR pueden quedar
   sin las 8 partes hasta su retiro. Documentar excepción en commit.

3. **Refactor cosmético reversible**: cambios al cuerpo markdown que no
   modifican `nivelRiesgo:` ni los 4 campos nuevos no disparan la regla.

---

## Cómo verificar conformidad

### Manualmente

Para auditar un agente ALTO:

```bash
node -e "
const a = require('js-yaml').load(require('fs').readFileSync(process.argv[1], 'utf-8').match(/^---\n([\s\S]+?)\n---/)[1]);
if (a.nivelRiesgo !== 'ALTO') { console.log('NO-ALTO'); return; }
const faltan = ['strategy','healthMetrics','steering','hardGuardrails'].filter(k => !a[k]);
if (faltan.length) console.error('FALTAN:', faltan.join(','));
else console.log('OK');
" agentes/X-swl.md
```

### Automáticamente

Hook `hooks/validar-intent-spec.js` (creado en F3) ejecuta esta validación
en PostToolUse sobre `Write|Edit` de `agentes/*.md`. Modo inicial:
`blocking: false` (warn-only). Promoción a `blocking: true` tras 2 semanas
estables sin falsos positivos, documentada en ADR-0027.

---

## Anti-patrones

- **Declarar `steering` algo que requiere enforcement**: "no eliminar
  archivos" sin hook que lo prevenga. Si importa, va en `hardGuardrails`
  con apoyo arquitectural.
- **Copiar `@reglas/X.md` completa en `hardGuardrails`**: referenciar, no
  duplicar. La regla evoluciona; la copia se queda atrás.
- **Health metrics como outcomes negados**: "latencia < 200ms" es outcome;
  "no degradar latencia mientras trabajas" es health metric.
- **Strategy demasiado vaga**: si la strategy aplica a cualquier agente,
  no es strategy de este agente. Borrar o especificar.
- **Promover a ALTO sin declarar las 6 partes**: violación directa de
  esta regla; el hook F3 (cuando blocking=true) lo previene.

---

## Relación con otras reglas

- `reglas/seguridad-agentes.md § Privilegio mínimo` — los campos nuevos NO
  escalan privilegios; son metadata declarativa.
- `reglas/fragmentos-compartidos.md` — el `_intent-spec` importado es un
  fragmento legítimo.
- `reglas/skills-estandar.md` — los skills cargables (`proceso-intent-engineering`)
  son la versión on-demand del fragmento.
- `reglas/registro-componentes-nuevos.md` — al agregar agente nuevo ALTO,
  registrar en manifiestos sigue siendo obligatorio.

---

## Cargar para aprender el framework

```
Skill("proceso-intent-engineering")
```

El skill explica cada parte con ejemplos, mapea Huryn (4 tiers) a SWL (3
tiers), enumera anti-patrones y entrega tabla de referencia rápida.

---

## Origen

Regla creada el 2026-05-18 como parte de Opción B (ver ADR-0025). Cubre el
gap detectado en análisis del artículo Huryn: SWL cubría 5/8 partes pero
no enforzaba sistemáticamente las 3 restantes (Strategy, Health Metrics,
Constraints distinguidas). La regla aplica solo a agentes ALTO porque
costos de declaración no compensan en agentes BAJO/MEDIO (los 6 agentes
del CONTEXTO original que eran BAJO/MEDIO se dejan opcionales).
