You already know what you did. This is how you turn that into something the next person can follow.
You just fixed something. Maybe it took twenty minutes, maybe it took an hour of digging before the actual fix was five commands. Either way, right now — while it's fresh — you know exactly what happened, why it happened, and what you did about it. Six months from now, when it happens again at 2 AM, you won't. Neither will whoever's on call.
A runbook is that knowledge, captured once, while it's cheap to capture, so it's free the next time. The problem has never been that SysAdmins don't know how to write one. It's that after you've already solved the problem, writing it up feels like doing the work twice — and it always loses to the next fire.
The fastest path to a runbook starts with something you already have: your terminal history from the incident, or a rough list of the commands you ran. You don't clean it up first. You feed it in raw and let the structure come from the prompt, not from you editing beforehand.
| Input | Where it comes from |
|---|---|
| Raw command history | history, script output, or a copy-pasted terminal session |
| What triggered it | The alert, the ticket, the symptom someone reported |
| What "fixed" looked like | How you confirmed it actually worked — the check, not just the fix |
# Piping recent history straight into sgpt, no cleanup first
history 50 | sgpt "Turn this into a runbook titled 'Disk Full on /var - Recovery Steps.'
Structure it as: Symptom, Diagnosis Steps, Fix, Verification.
I was clearing space on a web server after /var filled up from
runaway nginx logs. Keep every command, but group them under the
right heading and add one line explaining what each step is for."Earlier today, a site-wide bug was found: HTML anchor links that should only jump
within a page had picked up a stray target="TARGnnnn" attribute —
left over from an earlier automated pass that was supposed to apply only to external
links. The fix touched 210 files across the site.
The actual work was a handful of terminal commands: a dry run to find affected files, a review of the output, a backup tar, then the real run with a Perl script, followed by a verification pass. None of it was written down as a procedure — it didn't need to be, in the moment. But it's exactly the kind of fix that will happen again, on a different bug, and having the pattern documented saves working it out from scratch next time.
Nothing more than what was actually typed, pulled from history:
# (abbreviated — the real history had the full paths and script names)
find . -type f -name '*.html' | xargs fix-internal-targets.pl
# reviewed dry-run output — 210 files flagged, looked correct
tar -cf LessonPlans-08-09-2026.tar LessonPlans/
find . -type f -name '*.html' | xargs fix-internal-targets.pl -i
find . -type f -name '*.html' | xargs check-breadcrumb-targets.plsgpt "Turn this into a runbook titled 'Site-Wide Stray target= Attribute Fix.'
The bug: internal anchor links (href starting with # or a relative
path) had incorrectly picked up target=\"TARGnnnn\" from an earlier
automated script that should have only targeted external http(s)
links. Structure as: Symptom, How to Detect It, The Fix, Verification,
and a Rollback note since a .bak file is written for every changed
file. Keep every command exactly as I ran it."# Runbook: Site-Wide Stray target= Attribute Fix
#
# SYMPTOM
# Internal anchor links (in-page jumps or relative-path links)
# incorrectly carry target="TARGnnnn", a leftover from an earlier
# automated pass intended only for external http(s) links.
#
# DETECT
find . -type f -name '*.html' | xargs fix-internal-targets.pl
# — dry run only, makes no changes. Review the file list before
# proceeding to FIX.
#
# FIX
tar -cf LessonPlans-DATE.tar LessonPlans/
# — always back up first; the script also writes a per-file .bak
find . -type f -name '*.html' | xargs fix-internal-targets.pl -i
#
# VERIFY
find . -type f -name '*.html' | xargs check-breadcrumb-targets.pl
# — expect: "No breadcrumb/target issues found"
#
# ROLLBACK
# Every changed file has a matching .html.bak with the pre-fix
# content. To revert a single file: cp file.html.bak file.html
# To revert everything: restore from the pre-fix tar.That's a runbook in about two minutes of actual effort — most of which was writing the prompt, not the runbook itself. The next time a similar site-wide fix is needed, this is the starting template instead of a blank page.
Page 3 goes deeper on review discipline generally. For runbooks specifically, the cheapest check is this: could you hand this to the next person on call and have them successfully reproduce your fix without asking you a clarifying question? If there's a step you'd need to explain out loud, that's the step to fix before saving.