# Write the runbook for an alert that fires without one

An alert that pages somebody with no instructions, given a runbook verified against the real dashboards.

Category: Documentation and knowledge
Source: https://letsship.ai/use-cases/write-the-runbook-for-an-alert
Published: 2026-08-25

## Goal

Write the runbook for an alert that currently has none.

## Acceptance criteria

- Every step names the dashboard, query, or command it needs
- Each step has been run and confirmed
- It states how to tell whether the step worked
- It is linked from the alert definition

## What lands as proof

Every command and link exercised, so the runbook works for somebody who did not write it.

## Prompt

Copy this to an agent to open the ticket:

```text
Create a Linear issue in my team and assign it to the SHIP agent.

Title: Write the runbook for the {alert} alert

Description: Write the runbook for an alert that currently has none.

Acceptance criteria:
- Every step names the dashboard, query, or command it needs
- Each step has been run and confirmed
- It states how to tell whether the step worked
- It is linked from the alert definition

Before you create the issue, list this repository's alerts with no runbook link and replace {alert} with the one that fires most.
```

## Questions

### What does the agent actually change?

The ticket is scoped to one outcome: write the runbook for an alert that currently has none. Work that serves that outcome is in scope, and anything outside it is left for a separate ticket, so the pull request stays reviewable.

### How do I know the work is done?

The pull request carries the evidence, not only the diff. Here that means every step verified against the real dashboards, so a reviewer can confirm the result without reproducing the work locally.

### How much oversight does this need?

The run stops once the plan is written. Somebody reads the approach and approves it before any code exists, which is the cheapest moment to redirect the work.