# Runbook: si algo falla

Qué es: qué hacer cuando un agente se cuelga, se pisa con otro o pide lo que no debe.
Cómo se usa: identificá el síntoma en la primera tabla y seguí los siete pasos.
De dónde salió: Totem · megatotem.com · actualizado julio 2026

---

## Primero: clasificá

No todos los fallos se arreglan igual, y el error más caro es repetir el
intento sin saber qué falló.

| Síntoma | Clase | Qué hacer |
|---|---|---|
| El agente pide autorización y nadie la ve | Bloqueo de permiso | Abrí el hilo del agente y respondé desde ahí |
| Devolvió a medias y se detuvo | Dependencia | Le falta una entrada. Dásela o reducí el alcance |
| Falló una herramienta o un comando | Herramienta | Revisá el sandbox: puede estar pidiendo salir del workspace |
| Dos agentes entregaron lo mismo | Ambigüedad | El brief no separaba bien los objetivos. Reescribilo |
| Entregó algo prolijo pero vacío | Calidad | Faltaba criterio de terminado. Agregalo y repetí |
| Dos agentes se contradicen | Discrepancia | No promedies. Comparalos contra la evidencia |
| Un archivo perdió cambios | Pisada | Dos dueños para el mismo archivo. Repartí de nuevo |

## Los siete pasos

1. **Congelá el estado.** No sobrescribas los artefactos que sí sirven. Lo
   primero que se pierde en un rescate apurado es lo que estaba bien.
2. **Registrá** el fallo, el último paso que salió bien y la evidencia.
3. **No amplíes permisos** para destrabar. Es la reacción más común y la que
   convierte un problema de coordinación en uno de seguridad.
4. **Determiná la mínima entrada o decisión que falta.** Casi siempre es una
   sola cosa, y casi siempre es tuya.
5. **Reintentá una vez** con alcance reducido, o reasigná a otro agente. Una
   vez. Repetir el mismo pedido tres veces gasta el triple y devuelve lo mismo.
6. **Volvé a correr las pruebas afectadas**, no sólo la que falló.
7. **Actualizá la síntesis** y declará qué quedó incierto. Un artefacto parcial
   se marca como parcial; no se trata como aprobado porque el agente terminó.

## Casos concretos

**Un agente quedó esperando una aprobación que nunca viste.**
En el CLI, las aprobaciones pueden aparecer desde un hilo que no estás mirando.
El aviso trae la etiqueta del hilo de origen: con `o` lo abrís antes de decidir.
En flujos no interactivos, una acción que necesita permiso nuevo falla y el
error sube al principal.

**Un agente no puede escribir donde debería.**
Los subagentes heredan el modo de permisos del turno padre. Se elige antes de
delegar, no después. Si un agente personalizado declara `sandbox_mode` en su
archivo, ese valor manda para él, pero los ajustes que hiciste en vivo durante
la sesión —un `/permissions` o un `--yolo`— vuelven a aplicarse al hijo igual.

**Dos agentes editaron el mismo archivo.**
Repartí la escritura de nuevo y, si el trabajo es de código, dale a cada uno su
propio worktree o su propia rama. Que integre uno solo.

**El equipo se comió el presupuesto.**
Bajá `max_concurrent_threads_per_session`, pasá los agentes de lectura a un
modelo más chico y acortá el `AGENTS.md`. Todo lo que está en ese archivo se
paga en cada turno y en cada subagente.

**Los agentes coinciden y el resultado igual está mal.**
Buscá el supuesto compartido. Si los cuatro leyeron el mismo documento
equivocado, la coincidencia no es una confirmación: es un eco.