gilde

← All craftbooks

Ops Runbook

Documents and decksevalv1.0.0released 2026-06-05workflow: build-loop

Write an operational runbook or playbook a tired on-call engineer can follow at 3am without thinking — covering when to use it, prerequisites, numbered step-by-step procedures, verification, rollback, and escalation. Scopes the exact scenarios and prerequisites FIRST, writes unambiguous copy-pasteable steps with expected output and verification at each stage, then has a reviewer pressure-test it for gaps and dangerous ambiguity. Use for incident response, deploy/rollback procedures, and recurring ops tasks.

Steps

Entry step: scope. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Scope the runbookplannerentry

    trigger scenarios, prerequisites, success/rollback definition

    Show working prompt
    Define what the runbook covers before writing steps. Step 1: state the exact scenario(s) this runbook handles and, just as importantly, when NOT to use it. Step 2: list prerequisites — access/permissions, tools, environment, and any 'before you start' safety checks. Step 3: define what SUCCESS looks like (the verification signal that the procedure worked) and the conditions that should trigger a rollback or escalation. Step 4: outline the procedure as named stages in order (e.g. assess -> mitigate -> verify -> communicate), each to be expanded into numbered steps. Step 5: identify the destructive/irreversible steps that need an explicit warning. Step 6: write an acceptance-criteria checklist ('states when to use AND when not to', 'prerequisites + access listed', 'every stage has a verification step', 'a rollback procedure exists', 'escalation path with who/when', 'destructive steps carry a warning'). Write the scope + checklist via write_task_note AND to notes/scope.md. No detailed steps yet.
  2. Write the runbookcopywriter

    numbered, copy-pasteable steps with expected output + verification

    Show working prompt
    Write the runbook as runbook.md so a stressed on-call engineer can follow it literally. Step 1: open with a header block — purpose, when to use / when not to use, severity, and an at-a-glance summary. Step 2: write the prerequisites and a pre-flight checklist. Step 3: write each stage as explicitly NUMBERED steps; commands go in fenced code blocks ready to copy-paste, with placeholders clearly marked (e.g. <SERVICE_NAME>), and EACH step states the expected output and how to verify it before moving on. Step 4: add bold warning callouts before any destructive/irreversible step. Step 5: write a dedicated Rollback section (numbered, also verified) and an Escalation section naming who to contact, when, and how. Step 6: end with a 'how to confirm fully resolved' checklist. Keep sentences short and imperative; no ambiguity about which step to run when. On a loop-back, fix ONLY the named gaps. Write the path + stage/step counts via write_task_note.
  3. Review for gapsreviewer

    pressure-test the runbook for ambiguity and missing safety rails

    Show working prompt
    Pressure-test the runbook as if you must execute it half-asleep. Step 1: read every step and flag any that is ambiguous, assumes unstated context, or could be run out of order. Step 2: verify every destructive step has a warning and every stage has a verification signal. Step 3: confirm the rollback and escalation sections are actionable (real commands/contacts, not placeholders like 'contact the team'). Step 4: list concrete gaps with the exact step number and the fix needed. Step 5: write a review-findings note recording each gap as PASS/FAIL against the scope checklist. Write the findings via write_task_note AND to notes/review.md. If gaps remain, they must be fixed in the write phase before this passes.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    QA the runbook against the locked criteria. Step 1: read runbook.md and simulate following it step by step for the primary scenario. Step 2: check EACH acceptance criterion: states when to use and when not to, prerequisites + access listed, every stage has numbered steps with expected output and a verification, destructive steps carry warnings, a working rollback section exists, and an escalation path names who/when/how. Step 3: confirm there are no ambiguous steps or unresolved placeholders in the rollback/escalation sections. Step 4: incorporate the review findings from notes/review.md. Write PASS/FAIL per criterion with the offending step number on any FAIL.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "write" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license