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
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.
Extract the pattern, not the incident. Generalize: what is the reusable
diagnostic shape? Drop run-specific ids, timestamps, and host names.
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.
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.
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
1---2name: create-runbook3description: 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.4---56# Create Runbook78Capture procedural knowledge as a runbook in `runbooks/`, following the authoring9standard in `runbooks/AGENTS.md`. Read that file first — it defines the retrieval10mechanics, frontmatter contract, split/merge rules, fact-ownership model, contract11style, and validation. This skill is the procedure for producing one runbook.1213## When to use1415- After a multi-step investigation whose pattern others could reuse.16- To add a new stage to the investigation pipeline.17- To turn an ad-hoc recipe (a query pattern, an optimization) into a durable how-to.1819## Steps20211. **Check it should be a new file.** Search the existing registry22 (`panda search runbooks "…"` with a few phrasings). Content that would always be23 retrieved together with an existing runbook belongs IN that runbook — the split24 axis is co-retrieval, not topic count. Only mutually-exclusive-in-use content gets25 its own file.26272. **Extract the pattern, not the incident.** Generalize: what is the reusable28 diagnostic shape? Drop run-specific ids, timestamps, and host names.29303. **Engineer the retrieval surface first.** Write the `description` (what + when,31 third person, ≤1024 chars) and 3-6 `triggers` as the literal queries a caller would32 type, packed with exact identifiers (table names, error strings, API names). Body33 sections are embedded too (per-section child vectors), so mid-document facts are34 findable — but the metadata surface dominates ranking, so it decides whether the35 runbook wins the queries it should.36374. **Make it self-contained for its task.** Restate load-bearing facts briefly with a38 pointer to their canonical owner (`runbooks://<owner>`); reserve links for adjacent39 tasks. A required fact that lives only behind a link is a bug.40415. **Write to the standard's structure**: owns-line, Inputs (liberal), Output,42 Procedure; tables for decision matrices, numbered lists for procedures, positive43 directives, decisive rule up front. If the output feeds another stage: one filled44 example, ≤10 top-level fields, summary/reasoning before verdicts, confidence as45 `low|medium|high` per `runbooks://evidence_discipline`.4647## Verify4849- `go test ./runbooks/...` — frontmatter, refs, uniqueness.50- `panda search runbooks "<one of your triggers>"` returns the new runbook.51- `scripts/runbook-retrieval-check.sh` still passes (add a golden query for the52 new runbook while you're there).53- The server logs `Runbook registry loaded` with the new count.5455$ARGUMENTS
ethpandaops