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:

Terminal:

node ~/.claude/scripts/runbook-gen/resolve.js "<topic>" --print   # content for inline context
node ~/.claude/scripts/runbook-gen/resolve.js "<topic>" --json    # ranked matches

Terminal only — resolution is a topic→runbook lookup for agents and scripts; it needs no session.

Exit 1 means no runbook covers the topic yet — a signal to generate one.

Troubleshooting

Symptom	Likely cause	Fix
collect: ... 0 sources	All sources missing or wrong extension	Check paths; pass --ext if sources aren't .md/.txt.
Validator reports Missing YAML frontmatter	Editing a legacy runbook that predates the standard	Generated runbooks carry frontmatter; add the type/owner/last_reviewed block.
promote refused: ... already exists	A runbook of that name is already tracked	Review the diff; pass --force to overwrite intentionally.
no runbook matches topic	No promoted runbook overlaps the topic	Generate one with /runbook-gen.

See also

• /doc-audit — grade existing docs (the audit sibling).
• Documentation standard — the contract the validator enforces.
• Incident response runbook — an example of the target shape.