# Runbooks — symptom → cause → fix

> Start here when an operator reports a symptom rather than asking a question. Each runbook takes
> one complaint in the operator's own words and gives you a ranked list of causes, the single tool
> call that tests each one, and where to stop. Read the runbook for the symptom, not the whole
> knowledge base — the reference docs explain how a mechanism works, these tell you which mechanism
> to suspect first.

The rest of `knowledge/` is organized by **capability**: what a trigger is, how the workflow engine
works, what the eight v5Config fields do. That is the right shape for building an agent and the
wrong shape for debugging one, because an operator never arrives saying "I have a trigger-mode
problem" — they say *"el agente no responde"*. Without this layer the diagnostic path has to be
re-derived from first principles every session, which is how a session turns into fifteen
exploratory tool calls and a guess that it must be the prompt.

## How to use one

1. Match the symptom. If two runbooks fit, start with the cheaper one.
2. Work the hypotheses **in order**. They are sorted by how often each one turns out to be the
   cause, not by how interesting it is. Stop at the first hit — do not collect all of them.
3. Respect the stop conditions. When a step says "you're done", go to the fix and stop testing.
4. Only reach the prompt when the runbook says to. In our own fix history, configuration and
   automation explain the large majority of "the agent is behaving wrong" reports; the prompt is
   the last suspect for silence and the first only for wording.

## Where the rankings come from

The orderings are derived from the fix-logs and changelogs of our production agent fleet (874
structured fix entries and 597 changelog defect entries as of 2026-08-12), bucketed by symptom and
clustered by stated root cause. Counts are cited as documented cases, not as a share of all
incidents in the wild — an unreported incident never reaches a fix-log. Treat them as "this is what
actually breaks", not as calibrated probabilities.

Each runbook cites its evidence inline so you can tell a well-supported ranking from a thin one.
Cases are described by vertical and date, never by account — the handle was never what made the
evidence useful, and these docs ship to clients in the published playbook.

## The set

| Runbook | Operator says |
|---|---|
| [`agent-not-answering.md`](agent-not-answering.md) | "el agente no responde los DMs" · "my agent stopped replying" |
| [`agent-wont-stop.md`](agent-wont-stop.md) | "le sigue escribiendo a alguien que ya compró" · "it keeps messaging leads who bought" |
| [`zero-bookings.md`](zero-bookings.md) | "tengo cero agendas esta semana" · "nobody is booking" |
| [`conversation-went-wrong.md`](conversation-went-wrong.md) | "mirá esta conversación, algo anda mal" |
| [`not-live-yet.md`](not-live-yet.md) | "¿qué le falta para salir en vivo?" · "I deployed and nothing changed" |
| [`repeated-or-wrong-opener.md`](repeated-or-wrong-opener.md) | "repite el mismo mensaje" · "manda el saludo dos veces" |
| [`followup-never-fires.md`](followup-never-fires.md) | "el follow up no se envía nunca" · "it follows up with everyone" |
| [`notification-never-arrives.md`](notification-never-arrives.md) | "no me llegan las notificaciones cuando alguien agenda" |
| [`keyword-not-triggering.md`](keyword-not-triggering.md) | "la keyword no dispara cuando comentan" |
| [`resource-not-delivered.md`](resource-not-delivered.md) | "no se envía el pdf que configuré" · "el link no llega" |
| [`handoff-doesnt-stick.md`](handoff-doesnt-stick.md) | "pausé la conversación y el agente igual respondió" |
| [`too-many-or-truncated-messages.md`](too-many-or-truncated-messages.md) | "manda muchos mensajes seguidos" · "me llegó cortado" |

Several of them share a spine, because the platform does: an event flips a **custom property**, and
a **contact limit**, **workflow** or **notification** consumes it. When one of those links is
broken, the symptom depends only on which automation was downstream — silence, a follow-up that
never fires, an alert that never arrives, an agent that never stops. If you have ruled out the
obvious in one of those four, the same four links in another runbook are worth reading.

## Writing a new one

Keep the shape. A runbook that turns into an essay stops being usable mid-incident.

```text
SYMPTOM — how the operator actually says it, ES + EN
WHAT YOU NEED — the ids to collect before starting
HYPOTHESES — ranked, cheapest first. For each:
    what it looks like · the one tool call that tests it · the stop condition · the fix tool
WHEN TO STOP — what to put in report_feedback if none of it fits
```

Rules that keep them honest:

- **One tool call per hypothesis.** If testing a cause needs three calls, it is two hypotheses.
- **Never rank by elegance.** If the boring cause is the common one, it goes first.
- **Cite the evidence.** A ranking with no case behind it is a guess wearing a number.
- **State the stop condition.** Without it the reader keeps checking and ends up doing the full
  scan the runbook exists to prevent.