A rough timeline in, a readable record out — without losing the details that matter later.
A runbook is forward-looking — it's for the next person who hits the same problem. A change log entry is backward-looking — it's the honest record of what actually happened, for the person six months from now trying to understand why the system looks the way it does. They use similar raw material but they answer different questions, and a good change log entry resists the pull to become a second runbook.
The failure mode isn't usually laziness. It's that the entry gets written either too polished (all the messiness of what actually happened smoothed away, so the parts that would help someone later disappear with it) or too sparse ("fixed the thing," three words, useless to anyone including you in six months). AI is good at hitting the middle: enough detail to be useful, without turning a two-minute log entry into an essay.
| Include | Leave out |
|---|---|
| What changed, specifically — not "updated config" but which file, which setting, old value to new | Step-by-step reproduction instructions — that's what the runbook is for; link to it instead |
| Why it changed — the trigger, the symptom, the ticket number if there is one | Every command you ran along the way — the outcome matters more than the path, unless the path itself is the lesson |
| What you weren't sure about, if anything — a guess that worked is still a guess | Blame or narrative about who caused the problem — a change log is a record, not an incident report on a person |
| Rollback state — is there a backup, a tar, a way back if this turns out wrong | Speculation about root cause you haven't actually confirmed — say "suspected" if it's suspected |
Same underlying incident as Page 1's runbook example — the site-wide
target="TARGnnnn" fix — but this time the raw material is a rough
timeline of what happened over the course of the day, not a clean list of commands.
That's the more common real-world case: notes, not a script.
Unedited, the way they'd actually exist after a long session:
# rough notes, not cleaned up
- found the BAT/CAT anchor bug in CMDS nav this morning, small fix
- while looking at that, noticed a bigger pattern - internal links with
target=TARGnnnn that shouldn't have it
- built two perl scripts to find and fix it
- ran dry run first - 210 files would be affected, more than expected
but reviewed the list and it looked right, mostly .bak files and
legit external links got correctly excluded
- took a full tar backup before running for real
- ran the fix with -i flag, made a .bak per file too
- ran verification script after - came back clean, 0 issues left
- double checked with a few more grep passes to be sure nothing was
missed - all came back clean or explainable (custom-named targets
that were never part of the bug, doc text mentioning "target" etc)sgpt "Turn this into a change log entry, not a runbook. I don't need
step-by-step reproduction - I already have that in a separate runbook.
I want: what changed, why, and anything I was unsure about. Keep it to
a few sentences plus a short details section. Don't smooth over the
fact that the file count was higher than I expected - that's useful
context for next time."# 2026-08-09 — Site-wide stray target= attribute removed
Summary: Fixed a bug where internal anchor links (in-page jumps and
relative-path links) had incorrectly picked up target="TARGnnnn",
left over from an earlier automated pass that was meant to target
external links only. 210 files changed.
Details:
- Discovered while fixing an unrelated anchor bug in the CMDS nav;
turned out to be a broader pattern, not isolated to one file
- File count (210) was higher than expected going in - worth noting
for scoping similar fixes in the future
- Full backup taken before the change; per-file .bak also written
by the fix script as a second safety net
- Verified clean afterward via a dedicated check script, plus a
manual grep pass to rule out false positives (confirmed: only
legitimate external links and unrelated text remained)
Rollback: restore from pre-fix tar, or per-file from matching .bakNotice what's missing on purpose: no step-by-step "run this command, then this one." That's the runbook's job. This entry answers "what happened and why," which is the question someone reading the log six months from now is actually asking.
Read the entry back and ask: does this match what I actually remember happening? Not "does this sound professional" — does it match reality. A change log's whole value is being trustworthy later. An entry that's polished but wrong is worse than one that's rough but true.