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.