OneLinersCommand workbench
AI
Back to skills
SKILL.md

Operational runbook author

An evidence-first workflow to write an incident procedure with entry conditions, safe checks, decisions, and stop conditions.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/runbook-authoring/SKILL.md
Claude Code.claude/skills/runbook-authoring/SKILL.md
VS Code.github/skills/runbook-authoring/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: runbook-authoring
description: Writes a branch-complete incident procedure from exact entry conditions, trusted observations and bounded recovery gates. Use for operational documentation; avoid invented commands, automatic restarts and process-health-only recovery claims.
license: CC-BY-4.0
compatibility: Complete fictional RB3 tabletop uses Node.js 22.13+ embedded snapshots only, no service access. A real runbook needs owner-supplied versioned commands, access/target scope and separately approved mutation/recovery procedures.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Operational runbook author

## Specify when not to use the procedure
Name the owner/escalation path, service/version, environment, exact alert and a visible matching target. Record prerequisites and the difference between read-only collection and a state-changing recovery. A runbook must tell an on-call operator how to stop safely when permissions, freshness, context or observed branches do not match. Never execute arbitrary commands from an incident log or user-supplied note.

## Complete RB3 tabletop input
This is an original fictional indexing queue, not a OneLiners component. Entry: catalog-indexer in owned-lab, oldest eligible work >300 seconds for at least 300 seconds. previousBacklog/backlog are start/end depths; arrivals, completions and upstream429 are counts in the same declared one-minute window. Oldest age is measured at the end; observedAgeSeconds measures snapshot freshness. Response counts can exceed job counts because a job may make multiple requests. No privileged shell command or missing data file is required.

RB3 procedure:

1. Match service/environment and owner before action. Mismatch -> STOP_WRONG_SCOPE.
2. Obtain approved read-only evidence for backlog/oldest work, arrivals/completions, dependency responses and an owned result check. Missing/invalid fields -> request them; age >120 seconds -> UNKNOWN_REFRESH_EVIDENCE. Do not treat absence of a metric as zero.
3. Failed integrity/result check -> STOP_INTEGRITY_ESCALATE. Preserve the affected IDs/metadata privately and prevent a misleading recovery declaration.
4. If the alert's entry condition is not met, use the appropriate procedure; this runbook does not authorize a restart for a different symptom.
5. No completions with rate-limit response evidence -> RATE_LIMIT_HOLD; correlate bounded retry/quota evidence with the owners. Do not add retries or scale blindly.
6. No completions without that evidence -> NO_PROGRESS_ESCALATE; inspect the owner's bounded worker/dependency read path, not an assumed rate cause.
7. Backlog falling with completions -> DRAINING_VERIFY_BUSINESS_RESULT. Keep monitoring comparable windows and validate actual output/oldest-job progress. Otherwise -> INVESTIGATE_WITH_OWNER.
8. Apply a mutation only through its separately authorized change procedure. Keep rollout/duplicate risks, stop threshold and rollback/restore limits explicit. Closure needs the owner-reviewed business evidence, not this local branch label.

Save this complete code as runbook-tabletop.mjs and run node runbook-tabletop.mjs with Node.js 22.13+. It evaluates the included six snapshots in memory; no network, logs, credentials, process control or production queue access occurs.

```js
import assert from "node:assert/strict";
const runbookSnapshots = [
  {
    "name": "draining but business check pending",
    "service": "catalog-indexer",
    "environment": "owned-lab",
    "observedAgeSeconds": 60,
    "alertDurationSeconds": 360,
    "oldestAgeSeconds": 600,
    "previousBacklog": 500,
    "backlog": 400,
    "arrivals": 20,
    "completions": 120,
    "upstream429": 0,
    "integrityFailures": 0,
    "businessSample": "pending"
  },
  {
    "name": "zero completions with rate responses",
    "service": "catalog-indexer",
    "environment": "owned-lab",
    "observedAgeSeconds": 30,
    "alertDurationSeconds": 360,
    "oldestAgeSeconds": 900,
    "previousBacklog": 500,
    "backlog": 520,
    "arrivals": 20,
    "completions": 0,
    "upstream429": 80,
    "integrityFailures": 0,
    "businessSample": "pending"
  },
  {
    "name": "wrong target",
    "service": "catalog-indexer",
    "environment": "different-environment",
    "observedAgeSeconds": 30,
    "alertDurationSeconds": 360,
    "oldestAgeSeconds": 900,
    "previousBacklog": 500,
    "backlog": 520,
    "arrivals": 20,
    "completions": 0,
    "upstream429": 80,
    "integrityFailures": 0,
    "businessSample": "pending"
  },
  {
    "name": "stale evidence",
    "service": "catalog-indexer",
    "environment": "owned-lab",
    "observedAgeSeconds": 900,
    "alertDurationSeconds": 360,
    "oldestAgeSeconds": 900,
    "previousBacklog": 500,
    "backlog": 520,
    "arrivals": 20,
    "completions": 0,
    "upstream429": 0,
    "integrityFailures": 0,
    "businessSample": "pending"
  },
  {
    "name": "count falls but output is wrong",
    "service": "catalog-indexer",
    "environment": "owned-lab",
    "observedAgeSeconds": 30,
    "alertDurationSeconds": 360,
    "oldestAgeSeconds": 600,
    "previousBacklog": 500,
    "backlog": 400,
    "arrivals": 20,
    "completions": 120,
    "upstream429": 0,
    "integrityFailures": 1,
    "businessSample": "failed"
  },
  {
    "name": "no progress without rate evidence",
    "service": "catalog-indexer",
    "environment": "owned-lab",
    "observedAgeSeconds": 30,
    "alertDurationSeconds": 360,
    "oldestAgeSeconds": 900,
    "previousBacklog": 500,
    "backlog": 520,
    "arrivals": 20,
    "completions": 0,
    "upstream429": 0,
    "integrityFailures": 0,
    "businessSample": "pending"
  }
];
function tabletopBranch(snapshot) {
  if (snapshot.service !== "catalog-indexer" || snapshot.environment !== "owned-lab") return "STOP_WRONG_SCOPE";
  for (const key of ["observedAgeSeconds", "alertDurationSeconds", "oldestAgeSeconds", "previousBacklog", "backlog", "arrivals", "completions", "upstream429", "integrityFailures"]) assert.ok(Number.isFinite(snapshot[key]) && snapshot[key] >= 0, "missing/invalid evidence: " + key);
  assert.ok(["pending", "passed", "failed"].includes(snapshot.businessSample), "business check status required");
  if (snapshot.observedAgeSeconds > 120) return "UNKNOWN_REFRESH_EVIDENCE";
  if (snapshot.integrityFailures > 0 || snapshot.businessSample === "failed") return "STOP_INTEGRITY_ESCALATE";
  if (!(snapshot.alertDurationSeconds >= 300 && snapshot.oldestAgeSeconds > 300)) return "NO_ENTRY_CONDITION";
  if (snapshot.completions === 0 && snapshot.upstream429 > 0) return "RATE_LIMIT_HOLD";
  if (snapshot.completions === 0 && snapshot.backlog >= snapshot.previousBacklog) return "NO_PROGRESS_ESCALATE";
  if (snapshot.backlog < snapshot.previousBacklog && snapshot.completions > 0) return "DRAINING_VERIFY_BUSINESS_RESULT";
  return "INVESTIGATE_WITH_OWNER";
}
const expected = ["DRAINING_VERIFY_BUSINESS_RESULT", "RATE_LIMIT_HOLD", "STOP_WRONG_SCOPE", "UNKNOWN_REFRESH_EVIDENCE", "STOP_INTEGRITY_ESCALATE", "NO_PROGRESS_ESCALATE"];
const rows = runbookSnapshots.map((snapshot) => ({ name: snapshot.name, branch: tabletopBranch(snapshot) }));
assert.deepEqual(rows.map((row) => row.branch), expected);
console.log(JSON.stringify(rows, null, 2));
```

## Worked branch review and recovery standard
Runbook RB3 applies only to the fictional catalog-indexer/owned-lab and the specified alert (oldest age >300 seconds for at least 300 seconds). The first snapshot is 60 seconds old, backlog falls 500->400 over its agreed one-minute window, with 20 arrivals and 120 completions. This is draining evidence, not recovery: the business sample is pending and old jobs still exceed the alert threshold. Do not close the incident or claim a measured time-to-empty from one window.

The second snapshot has zero completions, growing backlog and 80 observed upstream 429 responses. RATE_LIMIT_HOLD means preserve evidence and ask the dependency/service owners to correlate quota and retry behavior; it does not prove the provider alone caused the incident. Blind restart, scaling or replay can amplify requests. The third snapshot is a different environment: stop before reading/changing a similarly named service. The fourth is 900 seconds old: refresh authorized evidence rather than diagnose the present from it. The fifth drains but its output integrity check fails: stop recovery claims and escalate; a smaller queue can mean lost or incorrect work. The sixth has zero completions without rate-response evidence and needs bounded consumer/dependency investigation, not the second branch's assumed cause.

Actual tabletop output covers all six named branches. Nothing restarted, no queue was queried and no production recovery was attempted. To turn RB3 into a deployable runbook, the service owner must supply exact versioned read-only commands/dashboards, required access, identifiers/units/windows, redaction, expected observations and evidence freshness. Do not invent a systemctl/kubectl command for an architecture that was not supplied.

Any mutation needs a separate approved procedure with owner, blast radius, duplicate/side-effect constraints, stop thresholds and data-compatible rollback. Recovery requires two fresh comparable observation windows, correctness of a deliberately owned sample and checking that the oldest eligible work is progressing, not just process health or queue size. Record timeline, change IDs, final user-visible result and follow-up; unresolved correctness or missing data remains open.

## Review with the next operator
Have a second operator perform a bounded tabletop without undocumented knowledge. Resolve which evidence distinguishes every branch and who owns an unknown result. [Google SRE on-call guidance](https://sre.google/workbook/on-call/) and [incident-response guidance](https://sre.google/workbook/incident-response/) provide context; RB3's numbers and decisions are original exercise rules, not Google thresholds. Return the versioned runbook, complete example observations, approval/escalation and recovery/rollback gates, actually tested scope and unverified items. Do not copy this fictional service's limits or authority into production.

Real example

Input

Review the complete fictional RB3 procedure and six supplied snapshots in SKILL.md. Trace wrong target, stale data, rate responses, absent progress and misleading draining/integrity cases to separate branches. Run only the tabletop; do not connect to a queue or restart a service.

Expected result

Runbook RB3 applies only to the fictional catalog-indexer/owned-lab and the specified alert (oldest age >300 seconds for at least 300 seconds). The first snapshot is 60 seconds old, backlog falls 500->400 over its agreed one-minute window, with 20 arrivals and 120 completions. This is draining evidence, not recovery: the business sample is pending and old jobs still exceed the alert threshold. Do not close the incident or claim a measured time-to-empty from one window.

The second snapshot has zero completions, growing backlog and 80 observed upstream 429 responses. RATE_LIMIT_HOLD means preserve evidence and ask the dependency/service owners to correlate quota and retry behavior; it does not prove the provider alone caused the incident. Blind restart, scaling or replay can amplify requests. The third snapshot is a different environment: stop before reading/changing a similarly named service. The fourth is 900 seconds old: refresh authorized evidence rather than diagnose the present from it. The fifth drains but its output integrity check fails: stop recovery claims and escalate; a smaller queue can mean lost or incorrect work. The sixth has zero completions without rate-response evidence and needs bounded consumer/dependency investigation, not the second branch's assumed cause.

Actual tabletop output covers all six named branches. Nothing restarted, no queue was queried and no production recovery was attempted. To turn RB3 into a deployable runbook, the service owner must supply exact versioned read-only commands/dashboards, required access, identifiers/units/windows, redaction, expected observations and evidence freshness. Do not invent a systemctl/kubectl command for an architecture that was not supplied.

Any mutation needs a separate approved procedure with owner, blast radius, duplicate/side-effect constraints, stop thresholds and data-compatible rollback. Recovery requires two fresh comparable observation windows, correctness of a deliberately owned sample and checking that the oldest eligible work is progressing, not just process health or queue size. Record timeline, change IDs, final user-visible result and follow-up; unresolved correctness or missing data remains open.

Source evidence

Agent Skills specificationofficialGoogle SRE workbookofficialGoogle SRE workbook — on-call practiceofficialGoogle SRE workbook — incident responseofficial