Lessons learned: a template and examples

A lessons learned entry is written for one reader: the person about to commit to work that looks like the work you have just closed. That reader needs it short enough to read in the minute before a decision, specific enough to change the decision, and kept where they are already looking. Most lessons learned documents miss all three, which is why they are written with care and never opened again.

What follows is the wording: a three-sentence template, six examples, each in a weak and a strong version, and how a lesson differs from a sprint retrospective and a post-mortem. Why one written lesson beats a workshop is a separate essay.

What a lessons learned record is for

It is not a summary of the project. The summary is the close: what was promised, what shipped and what differed. That honest close has to exist first, because a lesson drawn from a result nobody wrote down is an opinion.

It is a note to a future decision, which gives you a test to apply before saving one. If someone had read this entry on the day you committed, would they have asked for something different: a check, a smaller scope, a confirmation from another team, a later date? If not, the entry may be true and is still not worth keeping.

The template: three short sentences

We committed to X believing Y. It turned out Z. Before committing to similar work we will W.

• X, the commitment. Named the way it appears in your records, so the entry can be found by what the work was: a migration, an integration, a date a customer already had.
• Y, the belief. The assumption the commitment rested on, usually something treated as a fact when the work was sized. If nobody can say what was believed, write that. It is often the real finding.
• Z, what turned out. One observable fact about the work, the system, the vendor or the other team. This is the lesson itself: what you now know that you did not know when you committed. It is the one sentence the retrospective essay asks for. X and Y make it findable, and W turns it into a check.
• W, the check. One thing you will do before the next similar commitment, not during it. A check at commitment time has a moment and a person who performs it. Advice about delivering better has neither.

Write one entry for every closed commitment, on the day the outcome is recorded, and have the commitment's owner write it. That includes clean deliveries, where Z is "it held" and the reason it held is the lesson, and stopped projects, which often carry the most useful entry of the quarter. If you have five candidate lessons, write the one that would have changed the commitment. A list of five means nobody chose.

Six examples, weak and strong

Six situations, each with the entry people usually write and the entry the template produces. The projects are invented.

An estimate. Weak: "Estimates were too optimistic." True of most projects and usable by none.

We committed to the invoice migration at four FTE-months believing every legacy invoice used one schema. It turned out there were three, and reconciling them took six weeks on its own. Before committing to a data migration we will sample the oldest records and size it from what we find.

A dependency. Weak: "We need to communicate earlier with the platform team." The strong version names what was logged but never confirmed.

We committed to single sign-on for the partner portal believing the payments team's API change would land in May, because it was on their roadmap. It turned out nobody on that team had agreed to May. Before committing to work that needs another team we will get the date from that team, in writing, and record who gave it.

Scope. Weak: "Scope creep was a problem." The strong version points at the missing out-of-scope list.

We committed to carrier invoicing believing "the usual exports" meant CSV. It turned out finance also expected PDF and a monthly statement, and each arrived as a small favour after week five. Before committing to anything with reporting in it we will write the excluded outputs down and have the requester read them.

An early commitment. Weak: "We should not commit before we are ready." The strong version accepts that deadlines exist and improves the recorded exception.

We committed to the audit log early, for a customer renewal, believing the open question about retention periods was a detail. It turned out the answer differed by country and changed the storage design. Before committing early again we will give each open question in the exception an owner and a date.

A stopped project. Weak: "We should have stopped sooner." The useful lesson from a stopped commitment is about the day it was made.

We committed to the returns portal believing the pilot retailer would go live in the autumn. It turned out their launch depended on a contract that was never signed, and we stopped in week seven. Before committing to work that rests on one customer we will write down the condition that stops it and the date on which we check.

A clean delivery. Weak: "Went well, great teamwork."

We committed to the label reprint at two and a half FTE-months believing the printer vendor's API matched its documentation. It held, because an engineer spent two days testing it before we sized the work. Before committing to an integration we will spend the two days first.

Read the six weak versions together and they share one property: none names anything about the work. Each could be pasted onto a different project unchanged. That is the quickest test you have. An entry that fits any project is a value you already held, not something this one taught you.

Lessons learned vs retrospective vs post-mortem

All three look backwards. They differ in what they are about. Retrospective here means the sprint ceremony. The one-question retrospective argued for elsewhere on this site is the third row under another name.

A sprint retrospective is worth holding, and it leaves no record on any piece of work. A post-mortem, as software teams use the word, is the written review of an incident: an outage, a data loss, a failed release. It exists only when something broke, so an organisation that writes post-mortems and nothing else learns only from its loud failures. A commitment that arrived late and thin, with no outage, never gets one. Some teams also say post-mortem for an end-of-project review. That is a lessons learned exercise under another name, and the template applies to it.

Lessons learned is the project management term, where it usually means a document compiled when a project closes. The version here keeps the name and shrinks the unit: one commitment, one entry, written whether or not anything went wrong. If delivery included an incident, it still gets its post-mortem, and the entry can point to it.

Where to keep them so they are read

Keep the entry on the piece of work it came from, next to the recorded outcome. Separated from the outcome, a lesson floats free of the evidence that produced it. Then keep one view across all closed work, newest first. A view, not a second copy.

Storage is half of it. The other half is a moment for the reading, and there are three.

When similar work is being sized. Whoever gives the figure first opens the two or three closed commitments most like this one and reads their entries.

At the commitment. The owner says which past entries they read and what they changed because of them. "None were relevant" is an acceptable answer, as long as it is said.

At quarter end. Read the quarter's entries in one sitting, alongside the three counts that close a quarter. Lessons cluster. When the same W keeps appearing it is no longer a lesson; it is a missing rule. Three times is my tripwire, not a law. Move it into your readiness bar, where it is checked on every commitment without anyone having to remember. Do this for the repeat, not for every miss: a bar that gains an item each time stops being clearable.

If you use DeliverySheet

The three sentences are yours to type. The product holds the place and the rule. Learn opens on a committed demand only after its delivery outcome is recorded, whatever that outcome was, so a demand closed as not delivered gets a lesson too. It requires two things: a verdict on whether the committed value was realised (yes, partly or no) and a written answer to "What should we remember next time?" A third field, for clarifying the outcome, is optional. A verdict with no lesson does not close the demand, and neither does a lesson with no verdict; the server enforces both. The lesson is free text: the product does not check it against the template, and no AI drafts it.

The lesson is stored on the demand, directly under the outcome, and the demand counts as completed only when both exist. If the recorded outcome is changed afterwards, the lesson is cleared and has to be written again. For reading, the Reports page has a Completed & learned section. It lists completed demands with the result, the verdict and the opening lines of the lesson, newest first, each linking back to its demand. What the product does not do is put an old lesson in front of you when a similar request arrives. Reading before you commit is still your habit to keep.