Generate a Runbook

Generate a Runbook from Scattered Docs

Turn READMEs, wiki pages, code comments, and prior incident notes into one condensed, conforming runbook — a how-to / troubleshooting guide that doubles as scoped context for an operational agent. /runbook-gen is the generation sibling of /doc-audit: where the auditor grades what exists, the generator produces.

TL;DR

Slash command — generate a draft from a topic + sources (inside a Claude Code session):

/runbook-gen topic="recover a stuck warp-drive" runbooks/ docs/how-to/warp-drive.md

Terminal — review the staged draft, then promote it into runbooks/:

node ~/.claude/scripts/runbook-gen/promote.js runbooks/.drafts/recover-a-stuck-warp-drive.md

Terminal — resolve a topic to its runbook (for an agent, or to check coverage):

node ~/.claude/scripts/runbook-gen/resolve.js "recover a stuck warp-drive" --print

Generation is slash command only — the condensation step is the agent’s judgement and needs a Claude session; promotion and resolution are deterministic scripts, so they run from a terminal with no session. Nothing lands in runbooks/ until you promote it — the draft is the review buffer.

How it works

The flow splits deterministic work (scripts) from judgement (the agent). Scripts guarantee identical inputs produce identical context and gate results; the agent does only the condensation.

Stage	Owner	What happens
Collect	`collect.js`	Gather files / dirs / globs into one provenance-tagged bundle; missing sources are reported, not dropped.
Scaffold	`scaffold.js`	Emit a conforming skeleton (frontmatter + Purpose / When to use / Prerequisites / Steps / Troubleshooting / Escalation). Date via timelord.
Condense	the agent	Read the bundle, rewrite the placeholders into a real runbook — inverted-pyramid lede, imperative steps with expected output and decision points, merged duplicates.
Validate	`validate.js`	Gate against the documentation standard: frontmatter contract, `type: how-to`, required sections, kebab filename. Errors block; warnings advise.
Stage	the skill	Write the draft to `runbooks/.drafts/<slug>.md` (git-ignored) and hand off for review.
Promote	`promote.js`	Re-validate, refuse to clobber without `--force`, then move the draft into `runbooks/`.

Steps

1. Run the command with a topic and sources

Slash command:

/runbook-gen topic="<topic>" <source...>

Slash command only — the condensation that turns sources into a runbook is the agent’s judgement step, so there is no headless terminal generator.

A <source> is a file, a directory (recursed for .md/.txt), or a simple glob. Give it everything relevant — the generator condenses, so over-supplying sources is cheaper than missing one.

2. Review the staged draft

The draft lands at runbooks/.drafts/<slug>.md and is validated before you see it. Read it: are the steps right, the decision points real, the troubleshooting accurate? The draft is git-ignored — it exists only to be reviewed.

3. Promote it

Terminal:

node ~/.claude/scripts/runbook-gen/promote.js runbooks/.drafts/<slug>.md

Terminal only — promotion is a deterministic re-validate-and-move; it needs no Claude session.

Promotion re-validates (an invalid draft cannot land), enforces the kebab filename, and refuses to overwrite an existing runbook without --force. On success the file moves into runbooks/ and the draft is removed. Commit it when ready.

Promotion is also publication (#1447). runbooks/ is a declared source of the docs site, so a promoted runbook becomes a page under the site’s Runbooks section on the next deploy — at /runbooks/<slug> — and picks up its own row in runbooks/index.md, which is derived from the directory rather than hand-maintained. runbooks/.drafts/ is git-ignored and excluded from the site, so a staged draft is never published: it is a review buffer, and promotion is the moment the runbook goes public. Push a promoted runbook to master and the docs workflow republishes on the runbooks/** path trigger.

4. (Optional) Use it as agent context

A promoted runbook is loadable as scoped procedural context for an operational agent (e.g. incident triage). Resolve a topic to its runbook without knowing the filename: