Runbooks

A runbook is your team’s answer to “we’ve seen this before, here’s what to do.” In Firefight, runbooks are structured objects rather than wiki pages: a short summary, a rich procedure written in Markdown, and an ordered list of steps. When an incident matches a runbook’s conditions, the runbook attaches itself and appears in the incident channel, so the procedure finds the responder instead of the responder hunting for the procedure.

Runbooks live at Settings → Runbooks and require workspace admin access to manage.

Anatomy of a runbook

Part	What it is for
Name	What the procedure is called, like “Database failover”
Summary	A short description of when to use it. Shown in listings, in Slack, and to AI agents deciding whether the runbook is relevant
Content	The full procedure, edited with formatting (headings, lists, code blocks) and stored as Markdown
External URL	An optional link to a page elsewhere, like a wiki article or a dashboard, if part of the procedure lives outside Firefight
Steps	An ordered list of discrete actions responders should take, each with a title and instructions

Content and steps play different roles. Content is the narrative: context, decision points, queries to run, things to check. Steps are the checklist: concrete actions that responders can pick up, complete, and track one by one.

Conditions and automatic attachment

Each runbook carries conditions that decide which incidents it applies to. You can match on:

• Incident type, like Production or Security
• Severity, like Critical or Major
• Custom fields, including catalog references, so a runbook can target incidents affecting a specific service, environment, or any other field you have defined

Every condition supports “is one of” and “is not one of”, and an incident must match all conditions for the runbook to attach. A runbook with no conditions attaches to every incident.

Conditions are evaluated when an incident is declared, and again whenever the incident is updated. That second pass matters: severity and type are usually set at declaration, but the affected service often gets filled in later. A runbook scoped to a service attaches the moment that field is set.

Attachment only ever adds. Updating an incident never detaches a runbook that no longer matches, so a procedure that was relevant stays visible.

In the incident channel

When a runbook attaches, Firefight posts a message in the incident channel with the runbook’s name, summary, steps, and external link. If the runbook has steps, the message includes an Add steps as actions button. Pressing it creates one action item per step, in order, so the checklist becomes real, assignable, trackable work with the same pick-up and completion flow as any other action.

Everything is also recorded on the incident timeline: runbook.attached when a runbook attaches, and runbook.applied when its steps are turned into actions. Both are available as outbound webhook events.

For AI agents and the API

Runbooks are first-class context for AI. Attached runbooks are included in the incident context that Firefight’s own incident responder sees, and any external agent connected over MCP can browse them with two read-only tools: search_runbooks to scan names and summaries, and get_runbook to pull the full procedure and steps.

The REST API exposes the same data at GET /api/v1/runbooks and GET /api/v1/runbooks/:id, addressable by ID or slug, under the runbooks permission resource.

Writing runbooks that work

A few habits make runbooks dramatically more useful, for humans and agents alike:

• Lead with symptoms. The first thing a responder needs to confirm is “is this what is actually happening?”
• Make each step a single imperative action, not a paragraph. “Check replication lag on the standby” beats a wall of prose
• Include the exact queries, dashboard links, and commands. Every lookup a responder has to improvise costs minutes
• Keep the summary honest and specific. It is how the right runbook gets found, by people scanning a list and by agents choosing what to read
• Review after every incident that used the runbook. Stale procedures are worse than none