How to Humanize a Runbook After ChatGPT

Runbooks are read at 3am, one hand on PagerDuty, the other on a laptop balanced on a couch. ChatGPT runbooks look complete: numbered steps, "verify," "monitor," "escalate." They often break on step three—wrong namespace, stale dashboard link, feature flag name from last quarter.

Humanizing without verified commands produces polished outage extenders.

Related: humanize API documentation, humanize a design doc, humanize an incident postmortem, best practices for humanizing.

What on-call engineers punish in runbooks

Element	Weak AI runbook	Strong production runbook
Trigger	"When errors occur"	Symptom + alert name + threshold
Steps	Generic "restart service"	Copy-paste command with context
Prerequisites	Missing	Access, kube context, maintenance window
Rollback	Absent or vague	Exact undo with SHA or flag key
Escalation	"Contact team"	Slack channel, secondary, manager policy

Design docs explain why the system behaves this way. Runbooks tell you what to type before coffee. See humanize a design doc for decision records; link from the runbook header, do not merge them.

Lock steps before any model

Before ChatGPT or Human Writes, run and record:

1. Symptom — alert text, graph link, typical error string
2. Blast radius — services, regions, customer-facing vs internal
3. Prerequisites — VPN, role, kubectl config, read-only vs write
4. Happy path — commands or UI clicks that fixed it in drill or last incident
5. Rollback — undo command, flag flip, redeploy previous SHA
6. Escalation — who when happy path fails after N minutes
7. Verification — metric or log line that means "done"

If you cannot run (4) in staging, label the step unverified—do not let a model smooth that label away.

Do not paste production secrets into consumer chatbots. Redact tokens; work from internal paste templates your security team approves.

Typical runbook structure

Adjust to your ops culture, but 3am-friendly pages usually include:

1. Title + severity — what this fixes
2. When to use / not use — scope guardrails
3. Prerequisites — access and context
4. Procedure — numbered, one action per step
5. Verify — how you know it worked
6. Rollback — how to undo
7. Escalate — next human
8. Links — dashboard, API doc endpoint, related design doc

Section	Humanize?	Why
Shell commands / URLs	No	Copy-paste integrity
Thresholds / SLO numbers	No	Alert alignment
"When to use" prose	After steps locked	Reduces wrong-page drills
Failure branches	After steps locked	AI loves generic "check logs"

Paste context and warning sentences into Human Writes once. Restore every flag, URL, and command character-for-character.

Before and after (procedure step)

AI step:

3. Restart the affected service and monitor the system until metrics return to normal.

After commands locked from last incident:

3. Scale payments-worker to 0 then back to 3 (buy time without duplicate charges): kubectl -n prod scale deploy/payments-worker --replicas=0 Wait 30s; confirm queue depth flat in Payments queue dashboard. kubectl -n prod scale deploy/payments-worker --replicas=3 Verify: payments_process_success_rate > 99.5% for 5m. Rollback: redeploy payments-worker@9c2e1a (see deploy log 2026-08-14).

Second version survives muscle memory under stress.

Workflow

1. Start from the last postmortem or incident ticket—procedures born from pain stick.
2. Run the happy path in staging; copy exact commands and outputs.
3. Draft numbered steps from your notes—not from "write a runbook for service X."
4. Add If this fails branches only for paths you tested or saw in prod.
5. Link API documentation for integrator-facing endpoints; keep runbook ops-only.
6. Link design doc for architecture context in one line at top.
7. One Human Writes pass on wordy intros and warning boxes—not on steps.
8. Dry-run with someone not on the last incident; fix where they stall.
9. Set review date (quarterly or after every SEV-1).

When incidents finish, feed learnings back via incident postmortem and update the runbook the same week.

What not to do

• Publish commands you have not run this quarter.
• Humanize kubectl flags or API paths through paraphrase.
• Bury rollback below twenty troubleshooting bullets.
• Duplicate a design doc inside the runbook.
• Add length where a table or copy-paste block would scan faster at 3am.

Detector scores on internal wikis are irrelevant. Wrong namespace extends outages. See ethical AI checklist for team policy on assistants in ops docs.

Bottom line

Runbooks win on commands and links that work while tired, plus rollback and escalation on the same page. Human Writes is the clarity pass after steps are verified—not an excuse to add prose nobody will read.

Paste stiff prerequisite or warning paragraphs on Human Writes when every command matches what you ran in staging last Tuesday.