---
name: proceso-intent-engineering
description: >
  Framework "Intent Engineering" de 8 partes (Pawel Huryn, 2024-2026) para
  especificar agentes IA: Strategy, Objective, Desired Outcomes, Health Metrics,
  Org Context, Constraints (steering+hardGuardrails), Autonomy Boundaries, Stop
  Rules. Cargar cuando se cree un agente nuevo nivelRiesgo:ALTO, se audite uno
  existente, o se diagnostique un agente que falla por intent incompleto.
when_to_use: >
  Usar cuando el usuario menciona crear agente nuevo, refactor de agente ALTO,
  promover MEDIO a ALTO, agente que "se desvia del objetivo", agente que ignora
  restricciones blandas, intent spec, /goal, agentes que fallan por instrucciones
  ambiguas, health metrics, steering vs guardrails.
---

# Intent Engineering — el framework de 8 partes para agentes

## Cuándo cargar

- Diseñar un agente nuevo `nivelRiesgo: ALTO` (uso obligatorio según
  `reglas/intent-engineering.md`).
- Refactorizar un agente existente que falla por intent ambiguo.
- Auditar un agente con `/swl:revisar` y se detecta "deriva de scope".
- Decidir cómo materializar restricciones blandas (steering) vs duras
  (hardGuardrails) en un agente.
- Promover un agente de `MEDIO` a `ALTO` — la regla exige las 8 partes.

## Cuándo NO cargar

- Agente `BAJO` o `MEDIO` riesgo — declarar las 8 partes es overkill.
- Fix puntual de typo o ajuste de descripción de un agente existente.
- Crear skill (no agente) — el framework aplica a agentes, no a skills.
- Investigación de tooling externo (carga `investigador-swl`).

## Fuente y verificación

Adaptado de Pawel Huryn, *"Lead Agents Like Humans"* (Product Compass,
2026-05). La cita clave que justifica las 8 partes:

> "Lead agents the way good orgs lead empowered teams. OKRs (2016) →
> empowered teams (2020) → intent engineering (2024). /goal is two of
> eight parts." (Huryn, línea 5)

`/goal` (slash command de Codex y Claude Code) cubre las partes 2 y 3.
Las otras seis son responsabilidad del autor del agente.

## Las 8 partes — qué declarar y dónde vive en SWL

### Parte 1 — Strategy

Visión, mercado, propuesta de valor, tradeoffs. Huryn lo describe así:

> "You wouldn't onboard a senior PM with 'handle customer support.' You'd
> ground them in the strategy first: vision, market, value proposition,
> trade-offs." (línea 43)

**Dónde vive en SWL**: frontmatter `strategy: "..."` (máx 500 chars).
Cuando un agente operativo (`backend-python-swl`, `frontend-react-swl`)
necesita strategy específica al proyecto, hereda del `CLAUDE.md`. Cuando
el rol del agente impone trade-offs propios (`producto-prd-swl`,
`arquitecto-swl`), se declara explícito.

Ejemplo (`arquitecto-swl`):
```yaml
strategy: >
  Diseñar para evolvabilidad sobre completitud inicial. Módulos profundos
  (Ousterhout) sobre micro-servicios prematuros. ADRs sobre wikis. Reversible
  sobre óptimo cuando el costo de equivocarse es bajo.
```

### Parte 2 — Objective

El problema y por qué importa. Guía el juicio cuando las instrucciones se
agotan.

**Dónde vive en SWL**: campo `description:` del agente. Ya obligatorio
por schema. Para captura la regla "qué hace + cuándo invocarlo".

### Parte 3 — Desired Outcomes

Estados observables (no actividades) que prueban el objetivo cumplido.
Huryn enumera 4 reglas:

- Observable states, not agent activities.
- From the user's perspective, not the agent's.
- Measurable or verifiable without relying on agent self-report.
- Leading, not lagging.

**Dónde vive en SWL**: criterios de aceptación en `PLAN.md` por feature.
El `/swl:verificar` con goal-backward valida outcomes en 4 niveles.

### Parte 4 — Health Metrics

Lo que NO debe degradar mientras se persiguen outcomes. Cita textual:

> "Goodhart's Law: when a measure becomes a target, it stops being a good
> measure. [...] Health metrics steer; guardrails enforce." (líneas 134, 150)

**Dónde vive en SWL**: frontmatter `healthMetrics: [...]`. Diferencia
clave con outcomes: outcomes son lo que persigues; health metrics son lo
que proteges mientras persigues.

Ejemplo (`migrador-swl`):
```yaml
healthMetrics:
  - Integridad referencial de datos durante toda la ventana de migración
  - Tiempo de downtime <= 0 (expand-contract obligatorio)
  - Tests preexistentes verde antes y después
  - Sin warnings nuevos de ORM (N+1, lazy loading)
```

Si el agente detecta que una health metric está cayendo, **debe ser más
conservador, no más agresivo** — esa es la diferencia operacional con un
outcome.

### Parte 5 — Org Context

Sistema (otros agentes, hooks, tooling) + organización (proyecto, usuario,
dominio). No todo va en el prompt:

> "Core context (always needed) goes in the system prompt. Reference
> context goes in retrieval. Dynamic context (per-request) goes in the
> orchestration layer." (línea 159, parafraseada)

**Dónde vive en SWL**: `CLAUDE.md` del proyecto (org), `contextos/`
(dev/review/research), `INVENTARIO.md` (system context). El agente no
necesita declararlo — lo recibe vía carga inicial.

### Parte 6 — Constraints (los dos tipos)

Huryn separa muy claramente:

**Steering prompts (prompt-level)** — texto que el agente lee y debería
seguir, pero puede ignorar bajo presión:
- Behavioral guidance
- Risk preferences
- Tone and caution

**Hard guardrails (orchestration-level)** — restricciones aplicadas en
arquitectura, no en lenguaje:
- Tool restrictions
- Output validation
- Action gating
- Approval gates (HITL)

> "If a constraint matters, it must be enforced in architecture, not
> language. [...] The reasoning layer proposes. The orchestration layer
> enforces. If a constraint lives only in the prompt, it's a suggestion."
> (líneas 196, 197 paraf., 198)

**Dónde vive en SWL**:
- `steering: [...]` en frontmatter del agente (texto que el modelo lee)
- `hardGuardrails: [...]` declara qué hook/regla/schema enforza qué
  restricción. Sintaxis: `@reglas/X.md`, `@hooks/Y.js`, o texto inline
  si es específico al agente.

Anti-patrón: declarar como `steering` algo que necesita enforcement real
("no eliminar archivos" sin hook que lo prevenga). Si la restricción
importa, va en `hardGuardrails` con apoyo de hook/permiso/schema.

### Parte 7 — Autonomy Boundaries

Huryn define 4 niveles:

1. **Full Autonomy** — acciones reversibles, impacto limitado, modos de
   falla conocidos.
2. **Guarded Autonomy** — cambios visibles al usuario, riesgo medio.
   Requiere logging y rollback.
3. **Proposal-First** — decisiones estratégicas. El agente propone, el
   humano aprueba, el agente ejecuta.
4. **No Autonomy (Human-Required)** — compromisos legales, cambios
   irreversibles, acciones financieras.

**Mapeo a SWL** (3 niveles, no 4 — decisión consciente, ver ADR-0025):

| Huryn 4-tier | SWL `nivelRiesgo` | HITL? |
|---|---|---|
| Full Autonomy | BAJO | No |
| Guarded Autonomy | MEDIO | Solo en ramas críticas |
| Proposal-First | ALTO | Sí, antes de mutaciones irreversibles |
| Human-Required | ALTO + `permisos*: false` | Sí, siempre |

El nivel 4 de Huryn se modela en SWL como ALTO + permisos restrictivos en
frontmatter. NO se introduce un cuarto tier en el enum `nivelRiesgo`.

### Parte 8 — Stop Rules

Tres tipos de stop, todos load-bearing:

- **Halt** — restricciones en conflicto, confianza cae 2x consecutivas,
  `maxTurnos` alcanzado.
- **Escalate** — fuera de scope, tema legal/compliance detectado,
  frustración persistente.
- **Complete** — outcomes alcanzados, usuario confirma.

> "Halt and escalate are the load-bearing branches, and /goal ships
> neither." (línea 271)

**Dónde vive en SWL**:
- `maxTurnos:` en frontmatter — tope de iteraciones.
- Recovery Catalog en `reglas/seguridad-agentes.md § Recovery Catalog` —
  reprompt → reduce-autonomy → escalate → terminate.
- `notificador-swl` para escalado a humano vía Telegram/desktop.

## Cómo aplicar el framework a un agente nuevo

1. Cargar este skill antes de escribir el primer carácter del agente.
2. Importar `agentes/_intent-spec.md` con `fragmentos: [_intent-spec]`.
3. Declarar los 4 campos opcionales del schema:
   - `strategy:` (Parte 1)
   - `healthMetrics:` (Parte 4)
   - `steering:` (Parte 6 — soft)
   - `hardGuardrails:` (Parte 6 — hard)
4. Verificar que `description` cubre Parte 2 (Objective).
5. Verificar que `nivelRiesgo` mapea a Parte 7 (Autonomy Boundaries).
6. Verificar que `maxTurnos` está declarado si hay loop interno (Parte 8).
7. Org Context (Parte 5) vive en CLAUDE.md — no se duplica en el agente.
8. Desired Outcomes (Parte 3) vive en PLAN.md de cada invocación — no se
   hardcodea en el agente.

## Anti-patrones específicos a evitar

- **`steering` que debería ser `hardGuardrails`**: "no eliminar tablas"
  sin hook `proteccion-rutas.js` o equivalente. Si importa, va en
  arquitectura.
- **Health metrics como outcomes negados**: "no degradar latencia" es
  health metric; "latencia < 200ms p95" es outcome. La diferencia: outcome
  se persigue, health metric se protege mientras se persigue.
- **Strategy demasiado genérica**: "código limpio y mantenible" no es
  strategy de un agente — es default. Strategy debe nombrar el tradeoff
  específico que ese agente prioriza.
- **Autonomy Boundaries por ego, no por riesgo**: `nivelRiesgo: ALTO` no
  es prestigio; es declaración de que el agente toca cosas
  irreversibles. Si BAJO o MEDIO basta, no inflar.
- **Stop Rules ausentes**: agente sin `maxTurnos` ni recovery declarado
  puede entrar en loop infinito. Default seguro: 10-15 turnos.

## Gotchas no obvios

- **Health metrics no se enforce por sí solas**: el agente las lee y se
  comporta más conservador, pero NO hay hook que las verifique
  automáticamente. Diseñar telemetría que las capture si el agente es
  crítico.
- **`steering` y `hardGuardrails` aceptan `@reglas/X.md`**: cuando una
  restricción es global, no copiar el texto — referenciar la regla
  evita drift.
- **El framework no resuelve ambigüedad de objetivos en conflicto**:
  si dos health metrics chocan entre sí, la prioridad debe declararse
  como tradeoff en `strategy`.

## Referencia rápida — campos por nivelRiesgo

| Campo | BAJO | MEDIO | ALTO |
|---|---|---|---|
| `description` (Parte 2) | Obligatorio | Obligatorio | Obligatorio |
| `nivelRiesgo` (Parte 7) | Obligatorio | Obligatorio | Obligatorio |
| `maxTurnos` (Parte 8) | Recomendado | Recomendado | Obligatorio |
| `strategy` (Parte 1) | Opcional | Opcional | Obligatorio |
| `healthMetrics` (Parte 4) | Opcional | Opcional | Obligatorio |
| `steering` (Parte 6) | Opcional | Recomendado | Recomendado |
| `hardGuardrails` (Parte 6) | Opcional | Recomendado | Obligatorio |
| `fragmentos: [_intent-spec]` | Opcional | Opcional | Obligatorio |

## Origen

Skill creado el 2026-05-18 como parte de Opción B de integración
`temp/Lead-agents-like-humans.md` + `temp/DDIA*.md`. Ver ADR-0025 para la
decisión de scope. Fragment compartido `_intent-spec` es la
versión system-prompt-embebida; este skill es la versión invocable on-demand.
