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

# Inside Claude Code — generate a draft from a topic + sources
/runbook-gen topic="recover a stuck warp-drive" runbooks/ docs/how-to/warp-drive.md

# Review the staged draft, then promote it into runbooks/
node ~/.claude/scripts/runbook-gen/promote.js runbooks/.drafts/recover-a-stuck-warp-drive.md

# 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

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

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

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

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

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.

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:

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

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`.