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.

When to use

After completing an investigation or project
When shutting down or pausing a publication
Post-mortem for events
Handing off a project to someone else
Annual review of ongoing initiatives

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?"

Good example:

We built a comprehensive tagging system when users just needed full-text search. Three weeks on features no one used.

Bad example (too generic):

We learned the importance of user research.

Template structure

# LESSONS.md

## Project
- **Name:** [Project name]
- **Dates:** [Start - End]
- **Status:** [Completed / Abandoned / Ongoing]
- **Author:** [Your name]

## 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

### Critical failures
- [Thing that blocked progress - be specific]
- [Wrong assumption and its cost]

### Technical debt
- [Shortcut that hurt later]
- [Complexity that wasn't needed]

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

## The real problem
[This is the most important section]

What we thought: [Initial assumption]
What was actually needed: [Reality]
The gap cost us: [Time/effort/money wasted]

## Recommendations

### If continuing this project
1. [First priority]
2. [Second priority]
3. [Third priority]

### If starting fresh
- [What to do differently]
- [What to skip entirely]

### Tech stack verdict
- **Keep:** [Tools that worked well]
- **Replace:** [Tools that caused problems]
- **Add:** [Tools you wished you had]

## Reusable artifacts

| Component | Why it's valuable |
|-----------|------------------|
| [Name] | [Specific reuse potential] |
| [Name] | [Why someone else should use this] |

## Questions for next time
- [Unanswered questions worth investigating]
- [Things you'd research before starting]

Voice guidelines

Honest, specific, slightly self-deprecating
Like explaining to a friend why the project took twice as long
No corporate speak or blame-shifting
Name specific mistakes, not vague "challenges"

What to include vs exclude

Include	Exclude
Specific failures with context	Vague "learnings"
Actual time/cost of mistakes	Blame for individuals
Tools that helped or hurt	Generic best practices
Decisions you'd reverse	Obvious statements
Surprising discoveries	Information in other docs

The specificity test

For each item in "What didn't work," ask:

Can I name the specific decision?
Can I quantify the impact?
Would this help someone avoid the same mistake?

If no to any → Be more specific.

Examples of good vs bad entries

Bad - too vague:

Communication could have been better

We underestimated the complexity

Testing was insufficient

Good - specific and actionable:

Skipped schema validation on data files. Cost: 3 hours debugging a typo that caused silent failures.

Built custom date picker when browser native input would have worked. 2 days wasted.

No error messages when data fails to load—users just see blank screen.

"The real problem" examples

Weak:

We learned that requirements can change.

Strong:

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.

Red flags in your writing

If you find yourself writing these, stop and be more specific:

"Communication is key"
"We learned the importance of..."
"Going forward, we should..."
"Challenges included..."
"There were some issues with..."

These are placeholders for real insights. Replace them.

Journalism-specific templates

Templates are in the templates/ directory:

Template	Use for
`research-project.md`	Investigations, data journalism projects
`event.md`	Conferences, workshops, campaigns
`publication.md`	Newsletters, podcasts, ongoing content
`editorial-tool.md`	Newsroom software, AI tools

Template selection

What kind of project?
├── Investigation/analysis → research-project.md
├── Conference/workshop → event.md
├── Newsletter/podcast → publication.md
└── Newsroom tool → editorial-tool.md

The best retrospectives are written by people who got burned and want to save others from the same fate.

project-retrospective