Why I document every project with a postmortem

I used to finish a project, push it, and immediately start the next one. Same mistakes. Same blind spots. Same 2 AM debugging sessions that should never have happened.

The postmortem habit started by accident. A client project went sideways in a way I hadn't anticipated. I wrote down what happened — not to blame anyone, but to understand it. Three pages. Somewhere in those three pages, I noticed a pattern I'd seen twice before.

That was enough.

What a postmortem is (and isn't)

A postmortem is not a post-launch checklist. It's not a "lessons learned" section you copy-paste into every README and never read again.

It's an honest answer to three questions:

1. What worked? Not what you planned — what actually worked.
2. What failed? Not what almost failed. What actually broke, slowed you down, or cost you sleep.
3. What would you do differently? One concrete thing. Not a list of ten.

The part nobody talks about

The failure section is where the value is. It's also the hardest one to write honestly, because it means admitting mistakes in public. But "public" is the point. If the postmortem is only in your head, it doesn't change behaviour. Writing it down forces precision.

"I underestimated the complexity" is not a failure. "I committed to a two-week deadline without reading the third-party API docs first" is a failure. The second one teaches you something.

How I do it

I write the postmortem after the project has been live for at least a week. Not on ship day — your perspective is too distorted. After a week, the adrenaline is gone and you can see clearly.

Three sections. Plain text. No templates. I write until I have nothing left to say.

Then I publish it here.