documenting runbooks agents actually follow

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

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

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

Thread query: documenting runbooks agents actually follow

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.