# Agentic UX Playbook

Contrato práctico para diseñar productos donde una IA puede observar, proponer
y actuar. Úsalo en discovery, diseño, implementación y code review.

## 1. Declara el nivel de agencia

| Nivel | La IA puede | Patrón de interfaz |
|---|---|---|
| A0 Informar | Leer y explicar | Fuentes, límites y actualización |
| A1 Recomendar | Proponer opciones | Evidencia, comparación y rechazo |
| A2 Preparar | Crear un borrador o plan | Preview editable; nada externo cambia |
| A3 Ejecutar reversible | Actuar dentro de un límite recuperable | Estado persistente, log y undo real |
| A4 Ejecutar sensible | Afectar dinero, producción, terceros o datos | Preview, aprobación explícita y verificación |

El nivel debe describir una capacidad concreta. Evita controles vagos como
“modo autónomo” sin alcance, recursos, duración ni salida.

## 2. Clasifica cada acción

Antes de decidir si se ejecuta o se confirma, registra:

```yaml
action: refund_payment
effect: external
scope: one_payment
reversible: false
impact: financial
target_source: explicit_user_selection
requires:
  - preview
  - explicit_confirmation
  - strong_auth
  - outcome_verification
```

Evalúa cuatro dimensiones:

- impacto: bajo, medio, alto;
- reversibilidad: completa, parcial, imposible;
- alcance: local, compartido, externo;
- ambigüedad: objetivo explícito, inferido o incierto.

Una acción de alto impacto, irreversible, externa o inferida nunca debe cruzar
el commit boundary silenciosamente.

## 3. Define el commit boundary

Antes de una acción sensible muestra:

- qué va a ocurrir;
- sobre qué objeto o personas;
- diff o cambios exactos;
- costo, alcance y permisos;
- qué parte no puede deshacerse;
- cómo se verificará el resultado.

Ejemplo:

```text
Preparado, todavía no enviado

Reembolsar: MXN $1,249.00
Pago: pay_82K1
Cliente: Ana Torres
Motivo: cargo duplicado
Consecuencia: el reembolso no puede cancelarse una vez enviado

[Editar] [Cancelar] [Confirmar reembolso]
```

La confirmación debe describir la acción. Evita `Aceptar`, `Continuar` o un
dump de parámetros técnicos que la persona no pueda juzgar.

## 4. Usa permisos proporcionales al riesgo

Patrón recomendado:

- lectura local y operaciones sin efecto: permitidas;
- escritura reversible dentro del workspace: permitida con log y undo;
- red, datos externos o recursos compartidos: capability grant limitado;
- producción, dinero, comunicación externa o destrucción: aprobación explícita;
- credenciales, bypass de controles y ampliación de permisos: bloqueados o
  sujetos a una política externa al agente.

Prefiere límites estructurales:

- sandbox o VM;
- filesystem montado como read-only, read-write o no-delete;
- egress allowlist por operación, no sólo por dominio;
- tokens temporales y de alcance mínimo;
- identidad separada para el agente;
- límites de tiempo, costo y número de operaciones.

No uses una secuencia interminable de diálogos como sustituto de una frontera.

## 5. Diseña la corrección

Cuando la IA falla:

- permitir invocarla manualmente si no actuó;
- permitir descartar su intervención;
- corregir sólo la parte equivocada;
- pedir aclaración cuando el objetivo o target sea ambiguo;
- conservar el trabajo válido;
- explicar el fallo y el siguiente paso;
- verificar el outcome antes de declarar éxito.

Los resultados parciales deben nombrarse:

```text
18 de 20 facturas actualizadas
2 no cambiaron porque ya estaban pagadas
[Ver detalles] [Reintentar las 2 pendientes]
```

## 6. Expón actividad, no razonamiento privado

La persona necesita trazabilidad operativa:

- objetivo recibido;
- plan de alto nivel;
- herramientas y sistemas utilizados;
- datos o archivos afectados;
- permisos concedidos;
- acciones ejecutadas;
- resultado verificado;
- modelo, configuración y timestamp cuando sean relevantes.

No necesitas mostrar chain-of-thought privado. Un log verificable de acciones y
evidencia es más útil y más seguro.

## 7. Diseña también la ACI

Cada herramienta que consume el agente debe tener:

- nombre específico y namespace claro;
- propósito y límites;
- inputs inequívocos (`user_id`, no `user`);
- schema estricto;
- ejemplos y edge cases;
- distinción entre lectura y mutación;
- anotación de efecto destructivo o acceso abierto;
- respuesta concisa por defecto;
- filtros, paginación y truncamiento explícito;
- error accionable con la corrección esperada;
- outcome verificable.

Ejemplo:

```json
{
  "tool": "billing.refund_payment",
  "description": "Refund one captured payment. Irreversible after submission.",
  "input": {
    "payment_id": "pay_82K1",
    "amount_minor": 124900,
    "currency": "MXN",
    "reason": "duplicate"
  },
  "result": {
    "refund_id": "re_91P3",
    "status": "submitted"
  }
}
```

No combines `get`, `update`, `delete` y `publish` en una sola herramienta con
un parámetro ambiguo `action`.

## 8. Matriz de estados

Valida:

```text
idle
planning
waiting_for_input
waiting_for_permission
running
partially_completed
succeeded
failed_recoverable
failed_terminal
cancelled
timed_out
offline
```

Para cada estado define:

- qué ve la persona;
- qué puede hacer;
- si el agente sigue actuando;
- qué datos persisten;
- cómo se reanuda;
- cómo se anuncia de forma accesible.

## 9. Evals y señales

Por tarea registra:

- success rate en varios trials;
- resultado real, no la afirmación del agente;
- acciones y herramientas;
- errores de permisos y parámetros;
- reversión y fallos parciales;
- latencia, tokens y costo;
- intervenciones, cancelaciones y correcciones humanas;
- falsos positivos en confirmaciones;
- incidentes convertidos en regresiones.

Las pruebas deben incluir:

- actuar cuando corresponde;
- abstenerse cuando no corresponde;
- pedir aclaración ante targets ambiguos;
- resistir instrucciones inyectadas desde archivos, web y herramientas;
- no ampliar alcance ni buscar credenciales;
- no saltar verificaciones fallidas.

## 10. Definition of Done

- [ ] La UI distingue recomendar, preparar y ejecutar.
- [ ] El nivel de agencia tiene alcance, recursos y duración claros.
- [ ] Las acciones sensibles tienen commit boundary.
- [ ] Target, diff, costo y consecuencia son visibles antes de confirmar.
- [ ] Los permisos siguen riesgo y no producen fatiga rutinaria.
- [ ] Existen cancelación, corrección y recuperación proporcional.
- [ ] El sistema verifica el outcome antes de declarar éxito.
- [ ] El activity log permite reconstruir lo ocurrido.
- [ ] Los cambios de comportamiento se comunican.
- [ ] Las tools tienen schemas, límites y errores accionables.
- [ ] La suite evalúa actuación, abstención, ambigüedad e inyección.
- [ ] Una frontera técnica limita el blast radius.

## Add-on para un prompt de revisión UI/UX

```text
CALIBRATED AGENCY
Si la interfaz incluye IA o automatización:

1. Declara si la IA informa, recomienda, prepara o ejecuta.
2. Explica capacidades, límites, fuentes e incertidumbre útil.
3. Clasifica acciones por impacto, reversibilidad, alcance y ambigüedad.
4. Antes de acciones sensibles muestra target, diff, costo, permisos,
   consecuencias y mecanismo de verificación.
5. Permite editar, rechazar, cancelar, corregir, reintentar o deshacer según el
   riesgo y la reversibilidad.
6. Usa permisos mínimos y límites estructurales; no sustituyas seguridad con
   confirmaciones repetitivas.
7. Conserva un activity log de herramientas, recursos, acciones y outcomes sin
   exponer razonamiento privado.
8. Informa cambios de modelo, comportamiento o personalización que alteren las
   expectativas.
9. Audita la ACI: nombres, schemas, ejemplos, límites, efectos, paginación y
   errores accionables de cada tool.
10. Valida con evals que el agente actúe, se abstenga, pida aclaración y resista
    instrucciones no confiables.
```