Post-Mortems and the History Log Habit

Two kinds of records, two purposes

Production work generates two kinds of records: commits (what changed) and history entries (why and what was learned). Commits answer 'what does the code do today'. History answers 'what would I have done differently knowing this'. Skip the second and every regression is a fresh discovery.

What goes in a history entry

cwkPippa's history convention: a Markdown file per significant task at history/YYYY-MM-DD-task.md. Content: what was done, why (link to the trigger — incident, request, observation), key tradeoffs and decisions, files touched, gotchas discovered, and one-paragraph 'context that future-me would not get from git log'. The point is intent, not change.

The post-mortem subset

When something broke in production, the history entry becomes a post-mortem: timeline, root cause, blast radius, what worked in recovery, what would have caught it earlier. Blameless and specific. cwkPippa's history folder includes the JSONL fragmentation incident, the at-rest encryption rollout, the streaming-cancel bug — durable lessons for whoever operates next.

Principle: Commits answer what. History answers why. Both are required to operate; the second compounds.

Code

History entry template·markdown

# 2026-04-28 — JSONL Fragmentation Fix

## What happened

One paragraph: the symptom users saw, when it started, how it was detected.

## Root cause

What actually broke (link to the commit, function, or config). Be specific.

## Recovery

The steps that brought it back. What worked first vs what we tried first.

## Lesson

One or two sentences future-me wishes I had known. The non-obvious part.

## Files

- backend/store/sessions.py
- backend/services/healing.py

post-mortem one-liner in the runbook·markdown

## Streaming cancel bug (2026-03-15)

`asyncio.wait_for` around `__anext__()` cancels the async generator (Python
spec). Killed SSE during long tool calls. Fix: HTTP-level timeouts only;
never wait_for on a streaming iterator. See history/2026-03-15-stream-cancel.md.

Exercise

Pick one significant production task from the last month. Write a history entry: what, why, key decisions, lesson. Commit it to your repo's history folder. Plan to do this for every significant task going forward.

Hint

If 'I do not have a history folder', mkdir is the first commit. Future you needs the habit more than today you needs the polish.

Post-Mortems and the History Log Habit

Two kinds of records, two purposes

What goes in a history entry

The post-mortem subset

Code

External links

Exercise

Progress

Comments 0