Runbook template

When to use

• Shelf: build/runbooks/<topic>/
• kind: runbook
• Diátaxis mode: how-to (single operation, reader already decided to act)
• Readers served: operators repeating a known task; agents executing one command card without re-reading the playbook

Full rules: Writing style → Runbook spine.

Design rationale

• One operation per runbook — how-to docs fail when they teach the whole journey; runbooks are atomic (Diátaxis how-to).
• TL;DR names objective + done signal — operators need pass/fail before commands (Google procedures — lead with goal).
• Rollback section when reversible — production ops require explicit undo (Google SRE — runbook practices).
• Link to playbook for teaching — runbooks reference context; playbooks teach (separation of tutorial and how-to).
• Prerequisites as checklist — gates prevent running commands in wrong state (checklist pattern).

Copy-paste skeleton

---
title: "Operation name"
description: One sentence — what this runbook does and what verified success looks like.
sidebar:
  label: "Operation name"
  order: N
category: <topic>
kind: runbook
status: current
tags: [runbook, topic]
---

## TL;DR

**Objective** — the single outcome this card achieves. **Done when** &lt;observable signal&gt;. For the full workflow, see [Playbook name](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/).

## Prerequisites

- [ ] &lt;env, branch, access, backup&gt;
- [ ] &lt;tool installed&gt;

## Commands

### 1. &lt;Verb-first action&gt;

&lt;One sentence why.&gt;

\`\`\`bash
command --flag   # Expected: exit 0; &lt;short output&gt;
\`\`\`

- Expected: &lt;what you should see&gt;

## Verify

- [ ] &lt;signal 1&gt;
- [ ] &lt;signal 2&gt;

## Rollback

&lt;Optional — only when reversible. Exact undo commands + verify.&gt;

:::tip[Related]
[Teaching step in playbook](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/) · [Cheatsheet](/tech-stack/laravel/codecanyon/resources/cheatsheets/operations/)
:::

Anti-patterns

• Do not ship multi-phase teaching prose — that’s a playbook.
• Do not use playbook step spine with :::next unless this page is truly the next step in a chain.
• Do not omit Verify for destructive operations.

Worked example

• Code → test → ship
• System docs examples

Sources

• Diátaxis — How-to guides — single-task procedural docs.
• Google SRE Book — Ready for production — runbooks as operational command cards.
• Google developer documentation style guide — Procedures — prerequisites, commands, verification.
• Diátaxis — Overview — runbook vs tutorial separation.
• Writing style → Doc-type spines