Lessons Learned Template That Drives Change

Contributor
May 21
5 min read

Most "lessons learned" documents are filed in a folder no one revisits. The team feels good about producing one, the next project repeats the same mistakes, the next document records the same lessons. The template below tries to break the cycle by linking lessons to specific behaviors that will change.

The Working Template

# Lessons Learned: [Project Name]
Project completion: YYYY-MM-DD
Document date: YYYY-MM-DD
Authors: [Names]

## Project Summary
[2-3 sentences: what was the project, what was the outcome]

## What Worked
- Lesson: [What we did right]
  Why it worked: [Causal mechanism]
  How to repeat: [Specific practice to keep]

## What Didn't
- Lesson: [What went wrong]
  Why it happened: [Root cause, not symptom]
  What to change: [Specific action]
  Owner: [Who]
  Tracked as: [Ticket / process change / etc.]

## Surprises
- [Things we didn't expect, good or bad]

## Action Items
| Action | Owner | Due |
|--------|-------|-----|

## Distribution
[Who should see this and where it's filed]

The structure forces specificity. Each lesson connects to a concrete action.

What Worked

This section is often skipped or treated lightly. Don't skip it. Practices that worked are reusable; without explicit naming, they get forgotten.

For each item:

Lesson: the specific thing
Why it worked: the causal reason, not just "people were great"
How to repeat: what to do on future projects

Example:

Lesson: Daily standups with the customer during the beta phase Why it worked: Surfaced customer concerns within 24 hours, allowing us to fix issues before they became complaints How to repeat: Schedule daily 15-min customer syncs for any beta with > 5 customers

The "how to repeat" line is what makes the lesson actionable.

What Didn't

The harder section. Be honest.

For each item:

Lesson: the specific problem
Why it happened: root cause, not symptom
What to change: specific action
Owner: who'll make it happen
Tracked as: where the change lives in normal work (ticket, process update, etc.)

Example:

Lesson: Migration script took down production for 43 minutes Why it happened: Standard migration patterns don't account for table size; reviewer wasn't familiar with Postgres lock behavior on large tables What to change: Add migration linter rule for NOT NULL + default on large tables; require operational reviewer for migrations on tables > 10M rows Owner: Sam (Eng Lead) Tracked as: TICKET-2049, runbook update PR pending

Without the specific action and tracking, the lesson never becomes a change.

Why Lessons Don't Get Applied

Common failure modes:

Vague lessons. "We should communicate better." Useless. What would different communication look like specifically?

Unowned lessons. "The team needs to..." Which person?

Untracked lessons. Captured in a document, never connected to actual work. Six months later, no one remembers.

Lessons disconnected from systems. "We should test more." A pious aspiration. "We should add an integration test for the migration pattern" is specific.

No follow-up. The document is filed; no one looks at it during the next project's kickoff.

The template above tries to address each of these by demanding specificity, ownership, and tracking.

Surprises

Things you didn't expect. Both directions.

Positive surprises: capabilities you didn't know you had, partners who came through, tools that solved problems beyond their stated purpose.

Negative surprises: dependencies you didn't know existed, behaviors you didn't anticipate, costs you didn't budget.

Surprises are particularly worth capturing because they suggest blind spots in planning. Next time, when planning a similar project, the surprise should inform the planning.

Action Items: The Discipline

Most lessons-learned documents produce action items. Most action items don't get done. The discipline:

Each action item has a single owner.
Each has a due date.
Each is tracked in the team's normal work system, not just in this document.
Open items are reviewed quarterly.

Without these, action items rot.

Distributing the Document

A lessons-learned document filed in one team's folder reaches one team. Distribute broadly.

File in a central knowledge repository (wiki, drive)
Share with adjacent teams who might face similar projects
Surface in kickoff meetings for the next project ("we saw X last time; let's plan for it")
Tag with project type, technology, or domain for findability

A document that reaches the right reader on the next project is the document doing its job.

Cadence

When to produce a lessons-learned doc:

After project completion (major milestone, launch, or end of phase)
After incidents (often combined with the postmortem)
After significant pivots (the planning was wrong; capture the lessons)

For longer projects, periodic lessons-learned during execution can be more valuable than one big retrospective at the end. The team can apply lessons while the project is still in motion.

A Worked Example

# Lessons Learned: Workspace Switching Project
Project completion: 2026-08-15
Document date: 2026-08-22
Authors: Sam, Pat, Riley

## Project Summary
Built and launched self-service workspace switching for multi-workspace customers. Adoption hit 35% within 30 days; ticket volume on workspace topics dropped 78%.

## What Worked

- Lesson: Beta with 5 customers
  Why it worked: Real-world testing surfaced 4 edge cases that internal QA missed
  How to repeat: Beta with 3-5 customers for any user-facing feature; allocate 1-2 weeks for beta period

- Lesson: Feature flag rollout (10% → 50% → 100%)
  Why it worked: Caught a performance issue at 50% that would have affected all users at 100%
  How to repeat: Default to flag rollout for any change touching shared infrastructure

## What Didn't

- Lesson: Okta integration discovery happened too late
  Why it happened: Spike for SSO was scheduled in Week 3, but Okta had undocumented rate limits that only appeared in Week 6 testing
  What to change: Move SSO spikes to Week 1; include rate-limit testing in spike scope
  Owner: Sam
  Tracked as: TICKET-2089 (project template update)

- Lesson: Marketing was unprepared at launch
  Why it happened: Marketing was on the stakeholder list but engagement was Inform, not Consult. They didn't have time to prep their materials
  What to change: Marketing should be Consult, not Inform, for any customer-facing release
  Owner: PM
  Tracked as: PROCESS-12 (stakeholder map default)

## Surprises

- Self-service adoption hit 35% but most was from one user type (admins). End-users barely use the switcher. We assumed broader adoption.
- Support tickets dropped more than predicted (78% vs. 50% target)
- Mobile demand was higher than expected; mobile is being added to next quarter

## Action Items
| Action | Owner | Due |
|--------|-------|-----|
| Update project template with SSO spike in Week 1 | Sam | 09-01 |
| Update stakeholder map default for customer-facing releases | PM | 09-15 |
| Re-evaluate end-user education strategy | PM | 10-01 |

## Distribution
- Filed: wiki/lessons-learned/
- Notified: engineering, product, success
- To reference at next kickoff: Mobile workspace switching project (Q3 2026)

A useful document. Specific lessons, specific changes, owners, tracking, and distribution.

What Not to Include

Praise paragraphs. "Everyone worked hard." Doesn't help.
Detailed timelines. Belong in the project plan, not the lessons doc.
Long technical detail. Reference the docs and ADRs; don't replicate them.
Politics. "X team was difficult." Capture the actual issue (specific incident, miscommunication pattern), not the characterization.

Key Takeaway

A lessons-learned document is only useful if it changes behavior. Include both what worked and what didn't, with specific causes and specific actions. Every action item has an owner and is tracked in normal work systems, not just the document. Distribute broadly. Reference at the next project's kickoff. The biggest predictor of useful lessons isn't the document — it's whether the next project starts by reading the last one.

ShiftQuality