Lessons Learned Template That Drives Change
Updated: 13 hours ago
A lessons-learned document is judged by whether it was finished. It should be judged by whether the next project used it, and those are different documents.
The workspace-switching team wrote a model lessons-learned document. Every lesson had a cause, an owner and a ticket. The worst one read: identity-provider integration discovered too late — the SSO spike was scheduled for week 3, the provider's undocumented rate limits only appeared in week 6 testing. Change: move SSO spikes to week 1. Owner: Sam. Tracked as: TICKET-2089, project template update. Sam updated the template. The ticket was closed. The document was filed in the wiki under lessons-learned/.
Four months later the follow-on project, a mobile version of the same feature, hit a rate limit on the same identity provider in week 5 of its beta. Thousands of devices refreshed their sign-in tokens at the moment a release went out, and the provider throttled them. Nobody on the mobile team had read the earlier document. They had searched the wiki for mobile and token refresh; the lesson was titled for SSO spike timing. And the template Sam fixed was the web project template. The mobile project started from a different one.
Nothing in that document was wrong, and every action in it was done. It failed for a reason most templates don't address: it was written for the person closing the project, not for the person starting the next one. (Composite example drawn from patterns across several teams; the names, tickets and numbers are illustrative.)
Who a lessons-learned document is actually for
There are two readers. The writer reads it once, at the end of a project, when attention is already moving to the next thing; for them the document is a completion task, and the standard templates serve them well: a field for every lesson, an owner, a date, a box to tick. The second reader doesn't exist yet. They are the person running a kickoff months from now, on a project with a different name, different people and a different stack, who has thirty minutes to find out what the organisation already knows.
That second reader is where lessons-learned processes break, and the failure is well documented. NASA has run an agency-wide lessons-learned database for decades, one its managers were required to review on an ongoing basis. When the US General Accounting Office (now the Government Accountability Office) surveyed NASA program and project managers, 58 percent said current processes and systems did not let them retrieve the right lessons at the right time. A decade later, NASA's Inspector General surveyed the managers of 28 science and spaceflight projects: 16 had used the system during their project, and 12 had contributed to it. The lessons were being written. They weren't being found when they were needed.
The mechanism runs like this. The document is produced at the end, so it is shaped by what the writer remembers and judged by whether every field is filled. Nobody measures whether a later project used it, so nobody shapes it for retrieval, and it fails exactly where the GAO's managers said it fails: at the moment someone else needs it.
The test you can run: take your last three lessons-learned documents. For the project that started after each one, open its plan or risk register and look for a single line that exists because of the earlier document. Count them. Zero is the common answer, and it means your documents are records, not inputs.
Why a correct lesson still doesn't transfer
Two things stop a true lesson reaching the next project, and the workspace-switching document shows both.
It is written in the instance's nouns. "SSO spike", "week 3", "TICKET-2089", the provider's name. Those words describe what happened to this project. The next project will have different nouns (mobile, token refresh, push notifications), so a search for its situation never meets a lesson written about yours. The GAO's retrieval complaint is this problem at agency scale.
Its action fixes the instance. "Move SSO spikes to week 1" corrected one template. It said nothing about the underlying condition, which was calling an external service at a volume nobody had tested, and that condition comes back in any project that does the same, whatever template it starts from. This is the pattern the post-implementation review recurrence audit catches from the other end: an action item scoped to the event, completed, and followed by the same finding a few months later.
The fix is to write each lesson twice over: once as what happened, and once in terms the next project can match.
Field | Written for the writer | Written for the next kickoff |
What happened | "SSO integration discovered too late" | "Rate limits on an external service surfaced in week 6 of 8; the fix took 9 days and moved launch by a week" |
Why | "Spike scheduled in week 3" | "We tested the integration's behaviour, not its limits; the quota only appears at production-shaped volume" |
Applies when | (no field) | "Any project calling a third-party identity, payment or messaging API at a peak rate we haven't run before" |
Kickoff question | (no field) | "Which external services will this hit, at what peak rate, and has anyone run that rate against them?" |
Change | "Move SSO spikes to week 1" (web template) | "Add the kickoff question to the shared kickoff checklist every project template inherits" |
The test: pick one lesson from your latest document and give it to someone on a different team. Ask them to name a project of theirs it would apply to. If they can't, the lesson is still written in your project's nouns.
The template
Each lesson carries its instance and its mechanism, the condition under which it applies again, and the question that would have caught it in week one. The Seen before field connects the document to the ones that came before it.
# Lessons Learned: [Project name]
Completed: YYYY-MM-DD Written: YYYY-MM-DD (within two weeks of completion)
Authors: [names] Project type tags: [e.g. customer-facing, mobile, third-party API, data migration]
## Summary
[Two or three sentences: what the project set out to do and what it achieved,
against the success criteria it started with.]
## Lessons (what didn't work)
For each:
- What happened: [the instance, with one number: days lost, users affected, weeks late]
- Why: [the mechanism that produced it, not the symptom]
- Applies when: [the kind of project that will meet this again, in words a stranger would search for]
- Kickoff question: [the discovery question that would have surfaced this in week one]
- Change: [a change that works without anyone remembering it: a checklist item, a pipeline check, a default]
- Owner: [one named person] Tracked as: [ticket or process reference in the normal backlog]
- Seen before: [links to earlier documents with an equivalent lesson, or "first time"]
## Practices to repeat (what worked)
For each:
- What we did: [the specific practice]
- Why it worked: [the mechanism]
- Applies when: [the conditions it depends on, and where it would not help]
## Surprises
For each:
- What we didn't expect: [good or bad]
- The question nobody asked: [or "genuinely unforeseeable", if that is honest]
## Distribution
Filed at: [one central location, tagged with the project type tags above]
Read at: [the kickoff of the next project with a matching tag, named if known]
Leave out praise paragraphs, the full timeline (it belongs in the project record) and long technical detail; link to the architecture decision record instead. Characterisations of other teams don't belong either. If another team was involved, record the specific handoff that failed.
The Lessons Learned template in the ShiftQuality template library gives you the editable document, with an owner, a cause and a tracked action for every lesson.
One lesson, written twice
Back to the workspace-switching team. Here is the lesson as they wrote it, then rewritten with the template above.
As written:
Lesson: Identity-provider integration discovery happened too late Why it happened: SSO spike was scheduled in week 3, but the provider 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)
Rewritten:
What happened: The identity provider throttled sign-ins at production-shaped volume. Found in week 6 of 8; nine days to add backoff and request a quota increase; launch moved one week. Why: Our spike proved the integration worked for one user at a time. The provider's per-tenant quota isn't in the public docs, so only a load test at expected peak could have shown it. Applies when: Any project calling a third-party identity, payment or messaging API at a peak rate we haven't run before, on web or mobile. Kickoff question: Which external services will this hit, at what peak rate, and has anyone run that rate against them? Change: Kickoff question added to the shared kickoff checklist inherited by every project template. Owner: Delivery lead. Tracked as: PROCESS-31. Seen before: First time.
The first version is accurate and closed. The second one can be found by someone who has never heard of the project, and it hands them a question rather than a conclusion.
Now replay the mobile kickoff with the second version in the wiki. The tech lead filters the lessons documents by the tag third-party API rather than searching titles, and the kickoff question comes up. The team works out their peak: not steady traffic but every installed device refreshing its token within a minute of a release. One engineer spends two days running that rate against the provider's sandbox tenant and gets throttled well below the projected peak. Jittered token refresh goes into the first sprint instead of the beta post-mortem. (Illustrative.)
The lesson transferred because it described a condition (external service, untested peak) and a question, not a project. That is the discovery move this template is built around: every "what didn't work" is a discovery question that wasn't asked, and the document's job is to make sure the next kickoff asks it.
The test: for each lesson in your latest document, try to write the kickoff question. If you can't, you have recorded an outcome without understanding its cause, and the Why field needs another pass.
What worked needs a boundary
The what worked section is usually the thinnest part of a lessons document, and when it is filled in, it tends to read as praise: "the beta went well." The useful version names the practice and the mechanism, and then the conditions it depends on, because a practice copied into a project where those conditions don't hold fails quietly.
The workspace-switching team rolled the feature out behind a flag, at 10%, then 50%, then 100%, and caught a performance regression at 50% that would have hit every user. Written as "always use staged rollouts", that lesson will be applied to a database schema change, where a flag doesn't help because the migration runs for everyone at once. Written with its boundary, it reads: staged rollout caught a load-dependent regression because the cost grew with the number of active users; applies to changes whose cost scales with traffic; does not protect schema or data migrations, which need a rehearsed rollback instead.
The test: every "what worked" entry should have an Applies when that excludes something. If it applies to everything, it is a slogan, and the next team will over-apply it.
Surprises are the discovery gaps
A surprise is the plan meeting a fact nobody went looking for, and that makes the Surprises section the most direct record of what discovery missed. The workspace-switching team expected broad adoption of the switcher; almost all of it came from administrators, and ordinary users barely touched it. Nobody had checked who actually switched workspaces before the project started. The support tickets that justified the project came overwhelmingly from admins, and that data existed in the support system all along.
So the entry isn't "adoption was narrower than expected". It is: the question nobody asked: which user type generates the demand we're building for, and what data shows it? That question can be asked at the next kickoff. The surprise itself can't.
Some surprises are honestly unforeseeable: a vendor goes out of business, a regulator changes a deadline. Write those down as such. The field exists to separate the two, and a document whose every surprise was unforeseeable is usually one where nobody tried to answer the question.
The test: for each surprise, write the question that would have revealed it. Count how many could have been answered from data the organisation already had. That count is a direct measure of how much discovery your projects skip.
Closing the loop at the next kickoff
A lessons document becomes useful at one moment: when the next comparable project starts. Leaving that moment to chance is why the GAO's managers couldn't find the right lesson at the right time. Make it a fixed kickoff step instead.
The lessons read (30 minutes, at every kickoff). Run by whoever runs the kickoff, with the tech lead present.
Tag the new project with the same project type tags the lessons documents use.
Pull every lesson with a matching Applies when. Search that field, not the titles; titles carry the old project's nouns.
Read each kickoff question aloud and give it one of three outcomes: answered now (write the answer down), a spike with an owner and a date, or not applicable (with the reason).
Record the result in the new project's risk register, one line per lesson used, linking back to the source document.
The step is done when every matched question has one of the three outcomes. Its output is a count you can track: lessons used per kickoff. Over time it tells you whether your documents are inputs or archives, and the recurrence count in your post-implementation reviews tells you whether the changes they drove actually held.
Teams that already run pre-mortems can fold the lessons read into them: the matched kickoff questions make a strong first list of "how this could fail".
The test: at your next kickoff, see whether anyone opens a previous lessons document without being asked. If not, the read isn't a step yet, just an intention.
How much to write: the options
Not every team needs the full template on every project. The choice depends on how often similar projects recur and how expensive a repeated mistake is.
Option | Gains | Costs | Best suited for | Warning signs |
End-of-project document (this template) | Considered causes; one place to search | Written once attention has moved on; misses mid-project lessons | Projects with a likely successor of the same type | Written more than a month after completion; empty Applies when fields |
Living lessons register, updated during the project | Lessons captured while fresh and applied before the project ends | Needs a standing slot in the cadence; entries are rougher | Long projects, multi-phase programmes | Register untouched for several sprints |
Lessons folded into incident post-mortems | No extra ceremony; already blameless by design | Covers only what broke, never what worked | Operations-heavy teams | No "practices to repeat" anywhere |
Kickoff conversation only, no document | Cheapest | Depends entirely on who happens to be in the room | Small, stable teams | Same people at every kickoff; a departure takes the lessons with it |
The project-management standard has moved towards the second row. The sixth edition of PMI's PMBOK Guide treats the lessons-learned register as a project document updated throughout the project, not compiled at the end. For long work that is the better default. The fields above still apply; only the timing changes.
When this template is the wrong instrument
A live or recent incident. That needs a blameless post-mortem, with its own timeline and its own question: why the system failed, not what the project learned. The postmortem template and incident analysis that drives change cover it. Lessons from a post-mortem can feed this template afterwards.
One team's sprint-level learning. A sprint retrospective is faster and belongs to the team. The lessons template is for knowledge that has to cross a team or a project boundary.
A project with no plausible successor. A one-off migration of a system being retired doesn't need Applies when fields for its own sake. Write up only the lessons that apply beyond it, and skip the rest.
An organisation that punishes the "what didn't work" section. NASA managers told the GAO they were reluctant to share negative lessons for fear of not being seen as good project managers. Where that holds, the document gets sanitised and every lesson comes out vague. Fix that first; a better template won't.
What to do this week
Don't adopt a new template across the organisation. Rewrite one document.
Take your most recent lessons-learned document and pick its two most expensive lessons. Rewrite each with Applies when and Kickoff question, and replace the action with one that works without anyone remembering it. Then add a single line to whatever checklist your kickoffs use: search the lessons documents by Applies when for this project's type, and answer the kickoff questions. The next project that starts will tell you whether it worked.
Final takeaway
A lessons-learned document isn't finished when every field is filled. It's finished when a stranger, starting a project with different nouns, can find the lesson and come away with a question to ask in week one. Write each lesson as a condition and a question, and make the kickoff read it. Then count how often it does.
Sources
US General Accounting Office, NASA: Better Mechanisms Needed for Sharing Lessons Learned, GAO-02-195 (30 January 2002): 58 percent of surveyed NASA program and project managers said current processes and systems did not allow them to retrieve the right lessons at the right time; managers cited lack of time, lack of trust and intolerance for mistakes as barriers. https://www.gao.gov/products/gao-02-195
NASA Office of Inspector General, Review of NASA's Lessons Learned Information System, IG-12-012 (6 March 2012): of 28 project managers surveyed, 16 (57 percent) used the system during their project and 12 (43 percent) contributed lessons. https://oig.nasa.gov/office-of-inspector-general-oig/ig-12-012-2/
Project Management Institute, A Guide to the Project Management Body of Knowledge (PMBOK Guide), sixth edition (2017): the lessons-learned register, created in the Manage Project Knowledge process and updated throughout the project.
Related reading
Keep learning. This article is part of the Project Delivery & Change Management path in the ShiftQuality Learning Center. Ship change without breaking trust or production.
