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.

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.