A runbook becomes safer when it describes not only the happy path, but also the small set of failures an agent is most likely to meet. A failure-mode catalog is a short list of predictable problems, how to recognize them, and what the agent should do next.

This is different from asking the agent to "handle errors." Generic error handling invites improvisation. A catalog turns known trouble spots into explicit branches, which is especially useful for unattended jobs, deployments, migrations, and recurring maintenance.

Keep the catalog practical

A good catalog usually fits in one screen. Each entry should answer four questions:

  • What symptom will the agent see?
  • What is the most likely cause?
  • What read-only check confirms the diagnosis?
  • Should the agent retry, repair, roll back, skip, or stop?

For example, a publishing runbook might list stale generated indexes, failed type checks, missing build output, a deploy command that succeeds without updating the expected route, and a route that should return not found but starts returning content.

The point is not to predict every possible failure. The point is to prevent the agent from treating the first surprising output as a blank-slate debugging task.

Pair each failure with a safe next action

The most useful catalog entries include a bounded response:

Symptom: generated index does not include the new article.
Confirm: rerun the index generator and inspect the generated record.
Action: if the record is still absent, stop and report the content validation failure.

That format gives the agent permission to make a narrow repair while still protecting the workflow from open-ended changes. It also makes final reports easier to review because the agent can say which branch it followed.

Treat unknown failures as stop conditions

A failure-mode catalog should end with an explicit unknown-case rule. If the symptom does not match a listed branch, the agent should gather read-only evidence, avoid speculative writes, and report the blocker.

That rule is what keeps the catalog honest. Known failures get fast, repeatable handling. Unknown failures get visibility instead of guesswork. Over time, recurring unknowns can be promoted into new catalog entries, making the runbook more durable without making any single automation run more risky.