The hardest part of legacy modernisation is rarely the technology
Every legacy modernisation programme I have worked on has had a detailed technical plan. Architecture diagrams. Migration strategies. Integration maps. Test plans. Most of them have also significantly underestimated the time, cost, and complexity of the work. In almost every case, the underestimation was not in the technical dimension.
The technical challenges of legacy modernisation (migrating data, rewriting integrations, retiring old platforms, managing performance at scale) are real but solvable. Engineers are good at solving technical problems. What consistently derails modernisation programmes is the organisational and cultural dimension: the fact that legacy systems have owners, that workarounds have become processes, and that the people who know how the old system actually works are the same people being asked to replace it.
What the technical plan misses
Institutional knowledge is embedded in the legacy system. The most dangerous assumption in a modernisation programme is that the legacy system can be fully understood by reading the code and the documentation. In practice, significant business logic lives in the heads of the people who have operated and patched the system for years. It manifests in undocumented integrations, in edge cases that the original design never anticipated, and in operational procedures that exist precisely because the system does not behave as intended. You cannot migrate what you have not documented. And you cannot document what you do not know.
The new system asks different things of the organisation. Legacy modernisation almost always involves not just replacing technology but changing how work gets done. If the new system requires structured data where the old system accepted free text, that is a process change as much as a technical change. If the new platform removes a capability that a business unit has relied on (even an unofficial one), that is a political problem as much as a technical one.
The people most critical to success have the most to lose. The team members who understand the legacy system most deeply are often the ones whose expertise becomes less valuable once the modernisation is complete. Managing their engagement and anxiety is as important as managing the technical delivery.
The mitigation approach
Invest in a discovery phase that is explicitly focused on uncovering what is not in the documentation. Run structured knowledge extraction sessions. Map the informal processes alongside the formal ones. Treat the gap between documented behaviour and actual behaviour as a project risk, not a discovery by-product.
Build your change management plan at the same time as your technical plan, with the same level of resource and the same level of executive attention. The technology will be delivered by engineers. The adoption will be delivered by change managers. Both need a plan.