Lessons Learned & Known Issues
Captures post-migration observations — what went well, what could be improved, and concrete recommendations for future migrations. Populated during the post-migration review meeting held within two weeks of go-live while memories are still fresh. Over time, builds a searchable knowledge base that drives continuous improvement across the entire migration practice. Also covers the Known Issues register, where problems discovered post-migration are tracked until resolved or formally accepted.
Overview
The Lessons Learned module is a knowledge management tool, not a blame register. Its purpose is to capture observations from completed migrations — positive and negative — so that the team can continuously improve its approach, avoid repeating mistakes, and build on what worked well. Lessons are categorised (Process, Technical, Communication, Planning, and others) so they remain searchable and retrievable long after the project closes.
The module contains two distinct sub-areas. Lessons Learned is for retrospective observations: what happened, what was learned from it, and what the team recommends doing differently next time. Known Issues is a living register of problems discovered after go-live that have not yet been resolved — they may have workarounds in place, but they require tracking until formally resolved or accepted by the business. Both sub-areas are linked to migration events for context and traceability.
Over multiple projects, this module becomes the institutional memory of the migration practice. New project teams can review historical lessons before planning begins, avoiding common pitfalls and applying proven approaches from the outset. The post-migration review meeting should always be scheduled within two weeks of go-live — while experiences are still vivid and detail-rich. Lessons captured six months later lose the specific context that makes them actionable.
When to use this
- After go-live: Schedule a post-migration review within two weeks of each wave's go-live date and use this module to record the team's observations in real time.
- At project closure: Review all wave-level lessons and consolidate them into a project-level closure report that is shared with stakeholders and retained for future reference.
- After significant unexpected events: If a major incident, rollback, or unexpected delay occurs mid-project, record a lesson immediately while the details are clear — don't wait for the formal post-migration review.
- When onboarding a new project: Before planning begins, search historical lessons to identify known risks, proven techniques, and pitfalls specific to your environment or migration tool set.
- Quarterly practice reviews: Use the knowledge base to identify recurring themes across multiple projects — systemic issues that need process changes rather than per-project fixes.
Key features
Step-by-step instructions
Recording a lesson learned
Complete the three core fields that give each lesson its value:
- Description — what happened (the facts, objectively stated)
- Lesson — what the team learned from it
- Recommendation — what to do differently next time (specific and actionable)
Optionally link the lesson to the Source Migration Event for context.
Recording a known issue
Updating known issue status
Exporting lessons for project closure report
Important fields
Lessons Learned fields
| Field | Required / Optional | Description |
|---|---|---|
| Category | Required | The type of lesson: Process, Technical, Communication, Planning, or other configured options. Drives filtering and knowledge base search. |
| Description | Required | An objective account of what happened — the facts of the situation without blame or editorialising. Provides context for future readers who weren't present. |
| Lesson | Required | What the team learned from the event described in the Description. The insight extracted from the experience. |
| Recommendation | Required | A specific, actionable change the team should make next time. Avoid vague statements — recommendations should be concrete enough for another team to follow without further interpretation. |
| Owner | Required | The person responsible for ensuring the recommendation is implemented — either in the next project phase, the next project, or as a practice-level process change. |
| Source Migration Event | Optional | Links the lesson to the specific migration event (wave) it relates to. Provides context and enables wave-level retrospective reporting. |
| Date | Required | The date the lesson was recorded. Allows lessons to be sorted chronologically and helps readers understand which project phase they relate to. |
Known Issues fields
| Field | Required / Optional | Description |
|---|---|---|
| Title | Required | A concise, descriptive name for the issue. Should be specific enough to identify the problem without reading the full description. |
| Description | Required | A detailed explanation of the issue — what is happening, which systems or services are affected, and any steps to reproduce it. Include any error messages or observable symptoms. |
| Impact | Required | The severity of the issue: High (significant business impact, operations affected), Medium (notable inconvenience, workaround required), or Low (minor, cosmetic, or easily mitigated). |
| Owner | Required | The person responsible for resolving the issue or coordinating its resolution. Receives notifications and appears in status reports. |
| Status | Required | Current state: Open (acknowledged, not yet being worked), In Progress (actively being resolved), Resolved (fix implemented and verified), or Accepted (business has formally accepted this as a known limitation). |
| Workaround | Optional | Instructions for operating around the issue while a permanent fix is pending. Critical for operational teams who need to function despite the known problem. Document clearly and completely. |
| Date Raised | Required | The date the issue was first identified and recorded. Used for tracking how long issues have been open and for reporting purposes. |
Example workflow
Two weeks after Wave 1 completes, the project team holds a one-hour retrospective. Eight attendees join: the project manager, two migration engineers, three application owners, a network engineer, and the infrastructure lead. The facilitator opens Governance → Lessons Learned and records lessons as they are discussed.
Three lessons are logged under the Process category. The most significant: "The change freeze notification was sent at T-7, but several application owners had already scheduled maintenance tasks that conflicted with the migration window. Lesson: earlier notice is needed. Recommendation: send change freeze communication at T-14, not T-7, for all future waves." Owner: Sarah (PM). A second Process lesson captures that the rollback decision criteria hadn't been agreed before the window, which caused a 45-minute delay when a borderline decision needed to be made.
Two lessons are logged under Technical. One reads: "The RVTools export used for capacity planning was three days old at the time of execution. One VM had been re-sized after the export, causing a capacity miscalculation on the target host. Recommendation: always run a fresh RVTools export on the day of the planning session, never use a cached file." Owner: Tom (lead engineer).
The remaining three lessons fall under Communication — all relating to stakeholder updates during the migration window. At the end of the session, the facilitator exports all eight lessons to Excel and includes the file in the Wave 1 closure report sent to the steering committee. All lessons are now searchable by future project teams in the knowledge base.
Tips & best practices
The quality of lessons learned degrades rapidly as time passes. Details that seem memorable immediately after a migration window become fuzzy within a month. Schedule the retrospective while the team can still recall specific timings, decisions, and contributing factors. A lesson captured with full context two weeks after go-live is worth ten times a vague recollection captured at project closure three months later.
The Category field is how future teams find relevant lessons. A Technical lesson miscategorised as Process will be missed by engineers searching for technical pitfalls. Take a moment to select the most accurate category before saving. If a lesson spans multiple categories, choose the primary one and mention the secondary angle in the Recommendation field.
Lessons Learned is not just a register of problems. If something worked exceptionally well — a communication approach, a technical technique, a decision framework — record it. Positive lessons are equally valuable: they tell future teams what to preserve and repeat. A well-run rollback, an effective stakeholder briefing structure, or a clever pre-check script are all worth documenting for the benefit of the practice.
"Improve communication" is not a recommendation — it is an aspiration. A recommendation should be specific enough that someone who wasn't in the retrospective can implement it directly. Instead of "Improve communication", write "Add a T-14 all-stakeholders briefing email to the standard runbook for all future waves." The more specific the recommendation, the more likely it is to be acted on.
Common mistakes
Under pressure to move on to the next wave or close the project, retrospective meetings are often the first thing cut. This is a false economy. Each skipped review means the same mistakes are available to repeat on the next project. Treat the post-migration review as a mandatory project deliverable with a scheduled slot — not an optional extra.
A lessons register that contains only problems paints an inaccurately bleak picture of the project and provides no guidance on what to preserve. Future teams reading a purely negative register may over-correct, abandoning practices that were actually working well. Actively seek out positive observations in every retrospective and record them alongside the improvement areas.
A recommendation without an owner is decoration. If the Recommendation field contains a good idea but the Owner field is blank or assigned to "the team", the recommendation will not be implemented. Every recommendation must have a specific named individual who is accountable for taking it forward — either on the next wave, in the next project, or as a practice-level change proposal.
The knowledge base only delivers value if it is consulted. Before planning begins on a new migration project — especially before setting T-Minus schedules, communication plans, and risk registers — the project manager and lead engineer should search the Lessons Learned register for relevant experience. This should be a formal step in the project kick-off process, not an afterthought.