runbook

name	runbook
description	Produces a RUNBOOK.md (a repeatable operational procedure — trigger, numbered steps each with an observable verification, escalation) that is reversible throughout; primes the engineering + observability gates. Use to document an operational procedure as a safe, checkable SOP.

runbook

The procedure producer of the ops domain — it writes a RUNBOOK.md: the trigger that invokes it, the numbered steps each with an observable verification before the next, an abort/rollback at each risky step, and the escalation path when it goes wrong. The point is a procedure on-call can run safely and confirm at every step — no blind action. A runbook is a documented procedure, so it verifies by Review (sound, each step observable, reversible) until someone executes it; its Observation is deferred to that real run — a runbook is not "proven" until run. It documents the procedure; it does not execute it.

What this does / does not do

Does: resolve the runbook sub_target, write a RUNBOOK.md with trigger + prerequisites + numbered steps (action + observable verification + abort note) + escalation + post-run verification, and a receipt; the runbook verifies by Review. Does not: execute the procedure or any step (the operator / execution wave does, verified by Observation of the live result), plan a one-off ship (deployment), or run an incident (incident-response, which uses runbooks).

When NOT to use

• The work is executing the procedure — that is the operator / execution wave (Observation on the live result), not the runbook-producer.
• The work is a one-off deploy plan for a specific release — that is deployment; a runbook is the repeatable procedure.
• The work is responding to a live incident — that is incident-response (which may invoke this runbook).
• A current RUNBOOK.md for this procedure still fits and nothing changed — editing it beats rewriting an SOP.

Reference Routing

Situation	Reference
The RUNBOOK.md contract template	references/runbook-template.md
Per-sub_target must-declares · overlay · vocabulary	../acceptance/sub-targets.md · ../acceptance/overlay.md · ../vocabulary.md
Sibling ops sub_targets	deployment · incident-response

Inputs

• The operational task to proceduralize — what triggers it, the system/context it runs against, the desired end state.
• The ops domain pack (../vocabulary.md, ../acceptance/) + state/intake.json.

How to do it

1. State the trigger + prerequisites: the condition or event that invokes this runbook (alarm, schedule, request) and what must be true before step 1 (access, backups, a maintenance window).
2. Write numbered steps: each step is one action with the exact command/operation, then an observable verification — what the operator should see to confirm it worked before moving on. A step with no check is the blind-step failure mode.
3. Mark reversibility per step: each step's abort/rollback, and for any irreversible step, flag it with its blast radius so the operator knows the point of no return (the engineering gate).
4. Define escalation: when to stop and escalate, who to page, and the context to hand them — so a stuck run does not improvise.
5. State the post-run verification: the observable end state that means the procedure succeeded (and what a partial/failed run looks like).
6. Set the verification handoff: the runbook verifies by Review now; its Observation happens when it is executed — record that, do not mark it "proven" before a run.
7. Write RUNBOOK.md from references/runbook-template.md; name the procedure owner.

Gate (before marking complete)

• A clear trigger + prerequisites are stated.
• Every step has an observable verification before the next (no blind step).
• Each step's reversibility is marked; irreversible steps are flagged with blast radius (engineering).
• An escalation path (who / when / what context) is defined.
• A post-run verification (the observable success end-state) is stated (observability).
• The runbook verifies by Review; its Observation is deferred to an execution (not pre-claimed).

A gate failure is fixed before lock, not waived — these mirror the engineering/observability gates.

Output

• RUNBOOK.md at the product root (or ops/RUNBOOK.md) — persistence: Spec-Anchored. Trigger + prerequisites · numbered steps (action + observable verification + abort) · escalation · post-run verification · procedure owner.
• receipt (<workspace>/receipts/runbook-receipt-<ts>.json): base schema + sub_target, trigger, steps, steps_with_checks, escalation, reversible, runbook_path, observation_deferred, gate_checks. persistence: Spec-Anchored.

Proactive Triggers

• A step with no verification: add the observable check that confirms it worked — a blind step is how a runbook silently corrupts state.
• An irreversible step not flagged: mark the point of no return + its blast radius; the operator must know before they cross it.
• No escalation path: define who to page and when; a stuck run without an escalation improvises under pressure.
• A runbook marked "tested" with no execution: it verifies by Review until run; do not claim it proven before an actual Observation.

Completion Criteria

Done when: a RUNBOOK.md exists with a trigger + prerequisites, numbered steps each carrying an observable verification, per-step reversibility (irreversible steps flagged), an escalation path, and a post-run verification; it is Review-verified with Observation deferred; a runbook receipt records the gate checks.

Not done if: a step has no observable check; an irreversible step is unflagged; there is no escalation path; no post-run success state; or the runbook is claimed proven without an execution.

Next step: an operator executes the runbook, verified by Observation of the live result; incident-response may invoke it during an incident; deployment may reference its rollback steps.

Related Skills

• deployment: a plan for one specific ship (with its own rollback). runbook is the repeatable procedure; a deploy may reference a runbook's steps.
• incident-response: runs during a live incident and may invoke runbooks. runbook writes the standing procedure; incident-response handles the unplanned event.
• decompose: sequences a task card into build waves. A runbook sequences an operational procedure into verifiable steps — a different layer (an ops SOP, not a build plan).