add-doctor-runbook

Add Doctor Runbook

Extends an existing doctor (scaffolded by scaffold-doctor) with one new runbook — the internal markdown audit definition that drives a single health check in the doctor's agentic loop.

---

What you need before starting

• The doctor's project root (where scaffold-doctor deposited its output).
• A clear sense of what the new runbook should audit, what signals it reads, and what a violation looks like versus expected noise.

---

Flow

1. Locate the doctor's runbook directory and registration files

Inside the scaffolded doctor, runbooks live in skills/. The two registration files are:

File	Purpose
skills/index.ts	Runbook index — imports every runbook and exports a bundledSkills record.
config.ts	Mode config — assigns each runbook to runbooksDaily or runbooksWeekly.

Read both files before writing anything. Confirm the existing runbook names and the mode lists so you can slot the new runbook in correctly.

2. Gather runbook requirements

Ask the user (or derive from context) three things:

1. Purpose — what aspect of app health does this runbook audit? One or two sentences.
2. Signals and tools — which data sources, queries, or MCP tools will the runbook call? (e.g., CloudWatch log groups, a Looker query, a DB table.)
3. Healthy vs. violation — what does a clean run look like, and what specific conditions should trigger emit_finding?

Do not proceed to authoring until all three are clear. If any is ambiguous, ask a targeted question — a vague boundary between healthy and violation is the most common source of miscalibrated runbooks.

3. Author the runbook markdown

Create skills/<kebab-case-name>.md following the structure in ../scaffold-doctor/references/writing-runbooks.md.

Key requirements (enforced by the authoring checklist in that reference):

• Pull live config first. Step 1 of the Inspect section always reads thresholds from the app's config store. No hardcoded numbers anywhere.
• Parameterize every check. Time windows, count thresholds, feature-flag gates — all derived from the config you just read.
• Healthy runs emit zero findings. If the runbook would fire on a normal day, the threshold or classify logic is wrong.
• Separate violations from visibility. Informational observations (counts, rates, scorecards) go in the narrative; only actionable violations reach emit_finding.