Reference — generated from the toolkit

Source of truth: toolkit/skills/runbook-generation/spec.md. Edit it there; this page is regenerated on build.

Skill: runbook-generation

• Owner: AI + Support
• Version: 0.1.0
• Lifecycle: draft
• Phase: production

Trigger

Approaching the Production Readiness gate: every service hands Support a runbook, and at weekly release cadence hand-writing them doesn't scale. Draft from what the repo already knows — so humans verify a runbook rather than author one. Re-run whenever the observability config or deployment shape changes.

Inputs → outputs

• Inputs: the service repo (read-only) — observability config (dashboards, alerts, SLOs per the observability standard), deployment manifests and pipeline, gotchas recorded in repo memory — plus the runbook template.
• Outputs: a draft runbook per the template — overview, dashboards & alerts, diagnostics, known failure modes, escalation, recovery — with every diagnostic and recovery step marked 🤖 agent-executable or 👤 human-only.

Procedure

1. Map the alert config to the dashboards & alerts section: what each alert means, what pages, which dashboard shows it.
2. Derive diagnostics from the alerts and golden signals — the checks a responder runs when each alert fires.
3. Mine known failure modes from repo-memory gotchas and incident history where available, linked back to their source.
4. Extract the deploy/rollback shape from the pipeline into the recovery section, including how to verify recovery succeeded.
5. Mark each step conservatively: 🤖 only where the step is read-only or trivially reversible and verified as such; the default is 👤 human-only. Anything restart-, failover- or data-touching is human-only per authorise-the-irreversible.
6. Emit as a draft PR for the service owner and Support to verify. The runbook is accepted at Production Readiness via the support playbook — merging the draft is not acceptance.

Guardrails & permissions

• Read-only on the repo and config; no production access, ever — this skill writes about operations, it does not perform them.
• Never marks a step agent-executable on inference. Marking down to human-only is free; marking up to 🤖 requires a human's verification.
• Every dashboard, alert and link in the draft must resolve against real config — an unresolvable reference becomes a flagged gap, not plausible prose.

Failure modes

• Confident fiction — describing dashboards or alerts that don't exist (mitigated: resolution check above; gaps reported explicitly).
• Optimistic 🤖 marking — an irreversible step marked agent-executable (mitigated: conservative default plus mandatory human verification of every 🤖 step).
• Staleness — runbook drifting from reality after config changes (mitigated: re-run wired to observability/pipeline changes; the runbook records the config version it was drafted from).

Golden scenarios

Scenario	Input	Expected output	Pass criterion
Fixture service	repo with known alerts + deploy shape	runbook whose links and steps all resolve	zero fabricated dashboards/alerts
Irreversible steps	fixture with restart + failover procedures	both marked 👤 human-only	no irreversible step marked 🤖
Missing observability	fixture with no alert routing	gap flagged in the draft	gap reported, not papered over with prose