Incident write-up template

Copy this file into docs/incidents/YYYY-MM-DD-<short-name>.md the day something goes wrong. Write it while it’s fresh. Short and true beats long and late.

• Date: YYYY-MM-DD
• Impact: what visitors or customers saw, and for how long (for example: “site down, about 40 minutes”)
• Status: fixed / mitigated / still open

What happened

Two or three sentences a stranger could follow.

Timeline

All times in one time zone. Note how you found out.

• HH:MM — first sign of trouble (an alert, a customer email, you noticed)
• HH:MM — what you checked first
• HH:MM — the fix went in
• HH:MM — confirmed working

Cause

The real cause, not the first symptom. If you don’t know yet, say so.

The fix

What you changed, with the commit or setting.

What I ruled out

List every cause you tested and cleared, and how. This saves the next person (or your AI agent) from testing them again.

• Ruled out: <cause> — because <evidence>

Where the lesson goes

Tick each place you put it. A lesson written in only one place gets forgotten.

• A rule in the agent’s instruction file (CLAUDE.md), if it should never happen again. One or two sentences, linking back to this note.
• A memory or notes entry, for facts about the environment that aren’t in the code.
• A test or check, so nobody has to remember. This is the strongest option.
• Your knowledge notes, so the next big change starts from what’s already known.

Follow-ups

• <anything still to do, with a date>