project-retrospective

# Project retrospective writer

Create LESSONS.md files that capture institutional knowledge, especially failures. Think like a journalist writing about your own project — be specific, be honest, name the actual mistakes.

## Frame the retrospective: blame-aware, not pure-blameless

The 2024–2026 consensus in incident-analysis writing (PagerDuty, J. Paul Reed, Lorin Hochstein) is that pure blamelessness is neurobiologically unrealistic — humans default to blame. Healthier framing: acknowledge the blame bias exists and counter it deliberately. Source: https://postmortems.pagerduty.com/culture/blameless/

Cognitive biases to counter explicitly:
- **Fundamental attribution error** — blaming individuals for failures the system permitted
- **Confirmation bias** — looking for evidence that confirms a pre-formed narrative
- **Hindsight bias** — judging past decisions by knowledge that wasn't available at the time
- **Negativity bias** — over-weighting what went wrong vs. what worked

The voice rule isn't "no blame" — it's "name the system that permitted the human action, not just the action."

## Drop the single-root-cause framing

Allspaw's canonical critique (still the dominant view in 2024–2026) calls Five Whys / single-root-cause analysis "seductively satisfying and compellingly simple — but false." It locks analysts into a linear causal chain that terminates in individual blame. Source: https://www.kitchensoap.com/2014/11/14/the-infinite-hows-or-the-dangers-of-the-five-whys/

Use "how" narratives instead, gathering on four prompts:
- **Cues** — what signals were available, who saw them when?
- **Interpretation** — how did people make sense of those signals?
- **Goals** — what were people trying to accomplish?
- **Taking action** — what did they do, and what did they expect to happen?

The retrospective's job is to surface contributing factors, not declare a root cause.

## When to run a retrospective

Pre-define triggers before incidents happen, not after. Google SRE specifies criteria: user-visible downtime past a threshold, any data loss, on-call rollbacks, monitoring failures requiring manual discovery, stakeholder request. Source: https://sre.google/sre-book/postmortem-culture/

Translated to journalism:

| Trigger | Examples |
|---|---|
| Live-event failure | Live-blog downtime during election night, breaking-news embed breakage, paywall regression mid-investigation |
| Editorial process failure | Missed correction window, source-management breach, fact-check process bypass |
| Tool failure affecting subscribers | CMS migration regression, paywall logic affecting >X% of readers |
| Stakeholder request | Editor / publisher / source explicitly asking "what happened?" |

Pre-defined triggers prevent retrospective theater on routine work and ensure they happen on real failures.

## Timing: aim for under one week

Google's good-vs-bad postmortem comparison cites a "four months later" example as a quality failure because contributors' memories had decayed. Source: https://sre.google/workbook/postmortem-culture/

Recommended cadence:

| Project type | Target window |
|---|---|
| Live-event retro (election night, breaking news) | Same-day debrief, written within 48h |
| Tool / CMS incident | Within one week |
| Investigation or publication launch | Within one month of project close |
| Annual review of ongoing initiative | Once per year, scoped to discrete decision points |

The empirical floor is "fresh in contributors' minds." Past one week and the narrative gets reconstructed rather than remembered.

## For event-type retros, use AAR structure

The US Army's After Action Review (FM 7-0 Appendix K) was designed for facilitated post-event debriefs and fits live-news realities better than a project-close template. Source: https://www.first.army.mil/Portals/102/FM%207-0%20Appendix%20K.pdf

Four prompts:
1. **What was supposed to happen?**
2. **What did happen?**
3. **What was right or wrong about the difference?**
4. **How do we perform to standard next time?**

Run AAR immediately after the event with all participants — election night newsroom team, live-blog runners, breaking-news desk. Use `event.md` template for this; project-close templates are wrong for live-event retros.

## The critical section: "The real problem"

This is the most valuable part of any retrospective. It answers:

> "What did we THINK we were building vs. what was ACTUALLY needed?"

**Strong example:**
> We built an admin dashboard for editors when they actually needed a Slack bot. They live in Slack — forcing them to open a web app was friction they'd never accept. The dashboard has 2 monthly active users; the Slack bot prototype we built in a day has 47.

**Weak example:**
> We learned the importance of user research.

## Template structure

```markdown
# LESSONS.md

## Project
- **Name:** [Project name]
- **Dates:** [Start - End]
- **Status:** [Completed / Abandoned / Ongoing]
- **Author:** [Your name]
- **Retrospective written:** [Date — should be within timing window above]

## Summary
[One paragraph: what it did, what impact it had, why it matters]

## What worked

### Technical wins
- [Specific decision and WHY it worked]
- [Tool/pattern that saved time]

### Process wins
- [Methodology that helped]
- [Communication pattern that worked]

## What didn't work

For each item below, separate the system layer from the people layer.
"What did the system permit or require?" comes before "What did the
people inside that system do?"

### Critical failures
- **System:** [What the architecture / process / tooling permitted]
- **People:** [What humans did inside that constraint]
- **Cost:** [Quantified impact: hours, subscribers affected, money]

### Technical debt
- [Shortcut that hurt later — and why it was the rational choice at the time]
- [Complexity that wasn't needed]

### External factors
- [Things outside your control that impacted the project]

## The real problem

What we thought: [Initial assumption]
What was ac