runbook

Name: runbook
Author: testdouble

122stars12forks

How to install runbook?

testdouble/han/runbook

$npx -y skills add testdouble/han --skill runbook

Installs into the current project.

Summary

Create or update a runbook for an operational scenario — an incident an alert fires for, a recurring scheduled task, or a known failure mode on a live service — using a consistent template. Use when writing, drafting, authoring, or updating a runbook for an alert, incident, on-ca

Files · 1

View on GitHub

SKILL.md

1	# Create or Update Runbook
2
3	## Operating Principles
4
5	- YAGNI applies to runbooks themselves. Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md). A runbook is worth writing only when the scenario is grounded in something real: an alert that has actually fired, a documented incident, a recurring task that exists, or a known failure mode on a service that receives production traffic. Runbooks for hypothetical alerts, "best practice says we should have one," or "we'll need this someday" are YAGNI candidates and the runbook should be deferred until the scenario actually occurs. The canonical anti-pattern from project history: Sentry runbooks for staging-only Sentry where data isn't reaching production — alerts that will never fire because no signal flows. The user always wins; the rule's job is to make the cost of speculative runbooks visible.
6	- The companion evidence rule applies to the runbook's supporting evidence. Apply the evidence rule from [../../references/evidence-rule.md](../../references/evidence-rule.md) to the citations that ground the scenario: name the trust class of each piece of evidence (alert history, incident report, on-call rotation pattern); cite the actual artifact (dashboard URL, ticket ID, log query) rather than paraphrased recollection; and surface single-source claims as such rather than presenting them as settled.
7	- One runbook per invocation. The skill produces a single runbook file. Multi-runbook batches conflate scope; rerun the skill per scenario.
8	- Imperative commands with expected output. The template requires every step to show the exact command and what success looks like. Prose paragraphs in place of commands are an authoring failure the skill prompts against.
9	- Staleness is the failure mode. The template requires owner, last-validated, last-edited, and a change-history entry so decay is visible rather than hidden. The skill does not enforce a review cadence — that is a team-level workflow concern — but the metadata fields make the cadence auditable.
10	- Readability standard. Load and apply the readability rule from [../../references/readability-rule.md](../../references/readability-rule.md) as you write the runbook. Hold its default audience frame: a capable reader who did not do this work and lacks the author's context — here, the operator following the runbook during an incident.
11
12	## Project Context
13
14	- Git user: !`git config user.name \|\| echo unset` (!`git config user.email \|\| echo unset`)
15	- OS username: !`whoami`
16	- Today's date: !`date +%Y-%m-%d`
17	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
18	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
19
20	## Step 1: Determine Mode
21
22	Determine which mode to operate in based on the user's request:
23
24	\| Mode \| When \| Then \|
25	\|------\|------\|------\|
26	\| Creating new \| Drafting a runbook for a scenario the project does not yet have one for \| → Step 2 \|
27	\| Updating existing \| Modifying an existing runbook (new step, validation date refresh, escalation change) \| Read the existing runbook → Step 4 \|
28	\| Validating existing \| User says they ran the procedure end-to-end and wants to refresh `Last validated` and add a change-history entry \| Read the existing runbook → Step 4 (update mode, validation entry only) \|
29
30	## Step 2: Apply the YAGNI Preflight
31
32	Before discovering structure or gathering context, gate the work. Ask the user (or confirm from their request) which of the following describes the scenario:
33
34	1. An alert that has actually fired — name the alert, link the firing incident or alert manager record.
35	2. A documented incident or post-mortem — link it.
36	3. A recurring scheduled task that the team performs (weekly index rebuild, monthly cert rotation, etc.) — name the cadence and where the schedule lives.
37	4. A live failure mode on a service that receives production traffic, where the failure has occurred or is expected to occur with current measured pressure — name the service and the failure mode.
38	5. **Customer report or stakeholder commitme

People who liked this also viewed

6 picks

Type

runbook

122stars12forks

View on GitHub

How to install runbook?

testdouble/han/runbook

$npx -y skills add testdouble/han --skill runbook

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Create or Update Runbook
2
3	## Operating Principles
4
5	- YAGNI applies to runbooks themselves. Apply the evidence-based YAGNI rule from [../../references/yagni-rule.md](../../references/yagni-rule.md). A runbook is worth writing only when the scenario is grounded in something real: an alert that has actually fired, a documented incident, a recurring task that exists, or a known failure mode on a service that receives production traffic. Runbooks for hypothetical alerts, "best practice says we should have one," or "we'll need this someday" are YAGNI candidates and the runbook should be deferred until the scenario actually occurs. The canonical anti-pattern from project history: Sentry runbooks for staging-only Sentry where data isn't reaching production — alerts that will never fire because no signal flows. The user always wins; the rule's job is to make the cost of speculative runbooks visible.
6	- The companion evidence rule applies to the runbook's supporting evidence. Apply the evidence rule from [../../references/evidence-rule.md](../../references/evidence-rule.md) to the citations that ground the scenario: name the trust class of each piece of evidence (alert history, incident report, on-call rotation pattern); cite the actual artifact (dashboard URL, ticket ID, log query) rather than paraphrased recollection; and surface single-source claims as such rather than presenting them as settled.
7	- One runbook per invocation. The skill produces a single runbook file. Multi-runbook batches conflate scope; rerun the skill per scenario.
8	- Imperative commands with expected output. The template requires every step to show the exact command and what success looks like. Prose paragraphs in place of commands are an authoring failure the skill prompts against.
9	- Staleness is the failure mode. The template requires owner, last-validated, last-edited, and a change-history entry so decay is visible rather than hidden. The skill does not enforce a review cadence — that is a team-level workflow concern — but the metadata fields make the cadence auditable.
10	- Readability standard. Load and apply the readability rule from [../../references/readability-rule.md](../../references/readability-rule.md) as you write the runbook. Hold its default audience frame: a capable reader who did not do this work and lacks the author's context — here, the operator following the runbook during an incident.
11
12	## Project Context
13
14	- Git user: !`git config user.name \|\| echo unset` (!`git config user.email \|\| echo unset`)
15	- OS username: !`whoami`
16	- Today's date: !`date +%Y-%m-%d`
17	- CLAUDE.md: !`find . -maxdepth 1 -name "CLAUDE.md" -type f`
18	- project-discovery.md: !`find . -maxdepth 3 -name "project-discovery.md" -type f`
19
20	## Step 1: Determine Mode
21
22	Determine which mode to operate in based on the user's request:
23
24	\| Mode \| When \| Then \|
25	\|------\|------\|------\|
26	\| Creating new \| Drafting a runbook for a scenario the project does not yet have one for \| → Step 2 \|
27	\| Updating existing \| Modifying an existing runbook (new step, validation date refresh, escalation change) \| Read the existing runbook → Step 4 \|
28	\| Validating existing \| User says they ran the procedure end-to-end and wants to refresh `Last validated` and add a change-history entry \| Read the existing runbook → Step 4 (update mode, validation entry only) \|
29
30	## Step 2: Apply the YAGNI Preflight
31
32	Before discovering structure or gathering context, gate the work. Ask the user (or confirm from their request) which of the following describes the scenario:
33
34	1. An alert that has actually fired — name the alert, link the firing incident or alert manager record.
35	2. A documented incident or post-mortem — link it.
36	3. A recurring scheduled task that the team performs (weekly index rebuild, monthly cert rotation, etc.) — name the cadence and where the schedule lives.
37	4. A live failure mode on a service that receives production traffic, where the failure has occurred or is expected to occur with current measured pressure — name the service and the failure mode.
38	5. **Customer report or stakeholder commitme

People who liked this also viewed

6 picks

Type