Playbook Authoring
Turns a class of operational uncertainty — which path to take, when, and why — into a
reusable playbook a lead can use under pressure. Sibling of /runbook-authoring and
/sop-authoring. This skill writes judgment, not an execute script.
Playbook = WHEN / WHY / strategy / judgment under uncertainty; narrative + options
(this skill). Not a click-by-click execute script.
Runbook = trigger-driven, sequential, testable steps an operator/engineer executes
(incident, deploy, recovery, scheduled ops). Bus-factor-1. Repo/infra
context OK. (/runbook-authoring)
SOP = steady-state recurring COMPANY process; roles not named people; no code
required to understand. (/sop-authoring)
A playbook answers which runbook or script to run and when. A runbook performs how with guardrails. An SOP documents how the company operates a repeatable business process. Dated post-mortems record one incident; they are not playbooks — promote the reusable decision tree here, leave the timeline in the post-mortem.
Language rule
The skill's questions and working notes are in English. Generated playbooks follow the engagement's working language — English by default (public-facing ops docs are usually English), Spanish for Costa Rica engagements. Confirm if unclear.
Output directory
Resolve {playbooks-dir} first, in this order:
- If a business brain exists (a
business-brain/folder or a vault root with_procedimientos/— see/business-brain-setup), then{playbooks-dir}=<brain-root>/_procedimientos/playbooks/. Playbooks live with the other living procedures. - Otherwise,
{playbooks-dir}=./fractional-cto/playbooks/.
Flujo del skill
Paso 1 — Routing test (three-way ops taxonomy + docs)
Confirm the thing is actually a playbook. Use the shared three-way ops taxonomy in
references/documentation-taxonomy.md (playbook / runbook / SOP)
plus the usual product-docs cases.
Rule of thumb: if the reader must choose among branches before acting, it is a playbook. If they must execute numbered steps after the choice is made, it is a runbook. If a software engineer is not required to understand it, it is an SOP. Never treat "playbook" as a synonym for runbook or post-mortem.
If the type is ambiguous, run /document-this to resolve it before continuing.
Paso 2 — Confirm the reusable class of problem
Ask (or infer) the class of situation the playbook covers — not one dated ticket.
Capture:
- Trigger class — the family of symptoms (e.g. "public edge timeout while origin is healthy").
- Decision the reader must make — diagnose vs recover vs escalate vs wait for mitigation.
- Linked execute artifacts — diagnose script, recover/repair script, optional bootstrap prerequisite, optional mitigate/guard that should make manual recover rare.
- Roles — who decides, who executes, who is informed. Roles, not named people.
If there is no execute artifact yet, say so and offer /runbook-authoring for the
how after this playbook names the branches. Do not invent a full runbook here.
Paso 3 — Author the playbook
- Read the template:
${CLAUDE_PLUGIN_ROOT}/references/09-playbook-template.md. - Fill it. Writing discipline (the DNA of a real playbook):
- Artifact-type callout — state this page is a playbook (when/why). Scripts and numbered recover steps belong in runbooks.
- Header + reader's summary — a lead who reads nothing else can pick a branch.
- Artifact table by layer — playbook (this doc) · diagnose (read-only) ·
recover/repair (state change) · bootstrap (prerequisite) · mitigate (prevent
recurrence). Filename pattern:
playbook-{slug}.md,diagnose-{slug}.sh,recover-{slug}.sh(orrepair-). Do not name a new markdownrunbook-*.mdwhen it is actually a playbook. - Symptoms table — healthy vs broken probes, just enough to choose a branch. Do not paste a full diagnose script.
- Decision tree — the heart. Present-tense. Each leaf points at a section or a runbook, not a wall of commands.
- Option sections (§A, §B, …) — when this branch applies, what it means, short read-only hints, then a pointer to the runbook/script. Short diagnose hints are OK; a click-by-click recover script is not.
- Verification gate — how you know the chosen path succeeded (sustained healthy signal), not that a command exited 0.
- Out of scope — follow-ups that look related but are a different class.
- Name owners by role, not person.
- Dated incident callouts as evidence for a branch (
> Seen YYYY-MM-DD: …), not as a substitute post-mortem. - Playbooks do not replace scripts. If the how is missing, link a stub and
send the execute work to
/runbook-authoring. - Mitigation is the goal — after a durable guard exists, manual recover should become break-glass. The playbook stays for new root causes.
- Bilingual (EN + ES) when the operating team is bilingual.
- Write to
{playbooks-dir}/{slug}/playbook-{slug}.md.
Paso 4 — Quality checklist + 3 AM lead test
Run the 3 AM lead test: "could an on-call lead who has never seen this system pick the right branch from the decision tree + reader's summary alone, then hand the execute work to the linked runbook?" If not, the gaps are usually a missing branch, symptoms that do not discriminate, unnamed roles, or commands that belong in a runbook. Fix them before finishing.
A playbook fails the test if it is secretly a runbook (numbered execute steps with no decision tree) or secretly a post-mortem (one date, no reusable branches).
Paso 5 — Confirmación
Present the deliverables and how to use them:
playbook-{slug}.md→ "The playbook — when/why and which path to take."- Linked
diagnose-{slug}.sh/recover-{slug}.sh(if they exist) → "The runbooks — execute after the tree picks a branch. Author or update them with/runbook-authoring." - Post-mortem pointer (if this class already fired once) → "The dated narrative stays in the post-mortem; reusable judgment lives here."
Suggested next step:
"After the next real firing, fold the new branch or the wrong-path lesson back into the decision tree — a playbook improves every time someone almost chose the wrong option."
Notas para el modelo
/playbook-authoring(judgment),/runbook-authoring(execute), and/sop-authoring(company process) are siblings. The routing test is what separates them./pentest-playbook-setupis a security-test plan, not an ops playbook. Do not fold pentest methodology into this template.- Do not invent hostnames, vendor tickets, chat channels, or employee names. Use the Acme universe for examples (e.g. "AcmePay public-edge timeout playbook", "RapidEats checkout-queue playbook").
- Prefer linking versioned diagnose/recover scripts over pasting probe blocks into chat. The playbook names them; the runbook owns the commands.