create-runbook

---
name: create-runbook
description: Author a reusable runbook, or extract one from a completed investigation, following this repo's runbook standard. Use whenever a multi-step procedure, diagnosis, or recipe should be captured so future agents can reuse it.
license: MIT
---

# Create Runbook

Capture procedural knowledge as a runbook in `runbooks/`, following the authoring
standard in `runbooks/AGENTS.md`. Read that file first — it defines the retrieval
mechanics, frontmatter contract, split/merge rules, fact-ownership model, contract
style, and validation. This skill is the procedure for producing one runbook.

## When to use

- After a multi-step investigation whose pattern others could reuse.
- To add a new stage to the investigation pipeline.
- To turn an ad-hoc recipe (a query pattern, an optimization) into a durable how-to.

## Steps

1. **Check it should be a new file.** Search the existing registry
   (`panda search runbooks "…"` with a few phrasings). Content that would always be
   retrieved together with an existing runbook belongs IN that runbook — the split
   axis is co-retrieval, not topic count. Only mutually-exclusive-in-use content gets
   its own file.

2. **Extract the pattern, not the incident.** Generalize: what is the reusable
   diagnostic shape? Drop run-specific ids, timestamps, and host names.

3. **Engineer the retrieval surface first.** Write the `description` (what + when,
   third person, ≤1024 chars) and 3-6 `triggers` as the literal queries a caller would
   type, packed with exact identifiers (table names, error strings, API names). Body
   sections are embedded too (per-section child vectors), so mid-document facts are
   findable — but the metadata surface dominates ranking, so it decides whether the
   runbook wins the queries it should.

4. **Make it self-contained for its task.** Restate load-bearing facts briefly with a
   pointer to their canonical owner (`runbooks://<owner>`); reserve links for adjacent
   tasks. A required fact that lives only behind a link is a bug.

5. **Write to the standard's structure**: owns-line, Inputs (liberal), Output,
   Procedure; tables for decision matrices, numbered lists for procedures, positive
   directives, decisive rule up front. If the output feeds another stage: one filled
   example, ≤10 top-level fields, summary/reasoning before verdicts, confidence as
   `low|medium|high` per `runbooks://evidence_discipline`.

## Verify

- `go test ./runbooks/...` — frontmatter, refs, uniqueness.
- `panda search runbooks "<one of your triggers>"` returns the new runbook.
- `scripts/runbook-retrieval-check.sh` still passes (add a golden query for the
  new runbook while you're there).
- The server logs `Runbook registry loaded` with the new count.

$ARGUMENTS