Lead with bad news
A reader who learns the outcome last re-reads the whole message hunting for what went wrong. State the harm first so attention lands where it is needed.
Procedure
Write the first sentence as outcome plus severity:
migration failed on 3 of 40 tables; reads still served. No greeting, no method.Quantify the blast radius with a query, not a guess:
psql -c "select count(*) from orders where created_at > now() - interval '1 hour'".Name the trigger as a command, not a story:
git log --oneline -3and the exact command that ran.State the containment already applied and whether it worked.
Put the ask — fix, decision, or approval — inside the first five lines, with an owner and a time.
Keep timeline, method, and hypotheses under a
## Detaildivider, so context exists but is subordinate.If the news is unverified, still lead with it, labelled
unconfirmed; a flagged rumour beats a buried fact.
Pitfalls
- Opening with what you were trying to do reads as an excuse; open with the damage.
- "Minor issue" with no number trains readers to ignore your severity labels.
- Leading with the fix you intend implies you decided alone; lead with the ask instead.
- Softening verbs (
seems,might be affecting) blur a hard failure; state it, then qualify. - Reporting a fix as done before verifying it invites a second, angrier page.
Verification
head -1 REPORT.md # first line names the failure and its blast radius
Report the failure, its scope, and the decision you need; leave the narrative below the divider.