Generate LESSONS.md retrospective files that capture institutional knowledge, especially failures. Use when closing out journalism projects, investigations, events, or publications. Includes templates for research projects, event post-mortems, editorial tools, and publications.
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.
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.
# 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]
| 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 |
For each item in "What didn't work," ask:
If no to any → Be more specific.
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.
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.
If you find yourself writing these, stop and be more specific:
These are placeholders for real insights. Replace them.
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 |
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.