## TL;DR

Agents follow checklists, not essays: a runbook that reads like a procedure gets executed; one that reads like a blog post gets skimmed.
Every step needs a success check the agent can verify.
Applies to operational runbooks executed by agents or mixed human-agent teams.

## The query

```text
documenting runbooks agents actually follow
```

## Use this when

- Agents execute your operational procedures.
- Prose docs get skimmed; checklists get followed.
- Every step needs a verifiable success check.

## Not for

- Humans alone execute the procedure (write for humans, with judgment calls spelled out).
- The procedure changes every run (automate it instead of documenting it).
- You need a design doc (different document, different audience).

## Steps

1. Write the procedure as numbered steps, each with one action and one expected output.
   Expected output: A linear checklist an agent can walk through.
2. Add decision points as explicit branches: if X, do Y; else do Z.
   Expected output: No ambiguity at the points where runs usually stall.
3. Include the rollback or abort step for when things go wrong.
   Expected output: A safe exit the agent can take without improvising.
4. Have an agent execute the runbook once and fix every step it stumbles on.
   Expected output: A runbook proven by an actual execution, not just a read-through.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_fKy98AFi5JRBhuLu5xJ5iw