Reviewing a runbook

Audience: you are the second pair of eyes on a procedure someone else wrote.

The gates have already run. Schema, provenance, licence, graph invariants, capability consistency, secrets and injected instructions are all machine-checked (/spec/v1/errors lists every code). Do not spend your review on those. Spend it on the four things a gate cannot see.

Is the procedure correct?

No automated check knows whether restarting a consumer group is the right response to this alert, or whether the expect describes what the command actually prints. You are the only reader who can tell.

Read the commands. Run them if you can.

Is the risk labelling honest?

This is where review earns its keep. A step labelled read-only that writes is not caught by any gate — the label is a claim about the world, and only a human knows the world.

Ask specifically:

• Does anything labelled read-only mutate state, including caches, locks or leases?
• Does anything labelled reversible-write have a reversal that actually works, or one that exists in theory?
• Is blast_radius right? A restart that says resource and rebalances a whole consumer group is under-declared.

Under-declared risk is the failure mode with the worst consequences: it decides whether a supervisor demands a human, and whether the procedure may run under an adapter that cannot see shell access at all (§13.3).

Is the rollback real?

std/postgres-drop-stale-replication-slot recreates the slot it dropped — and does not recover the WAL already released, which the record says in its prose. That is an honest rollback.

A rollback that silently fails to undo is worse than none, because the gate before the destructive step is where someone weighs the trade, and they weigh it using what the record told them.

Does the graph match the procedure?

Walk the happy path. Then walk each on_fail. A route that goes somewhere surprising is usually a real bug in the procedure rather than in the drawing — the graph is where a disagreement between what someone meant and what they wrote becomes visible.

What two-person review is actually for

Two reviewers are required for destructive and irreversible records, for promoting a publisher, and for anything entering std/ (§15). Everything else merges on green gates.

That is not a formality. It is an admission that the four questions above cannot be automated, and that the records where getting them wrong is unrecoverable deserve two people who have each asked them.