DEV Community: Kerrial Newham

The Boardroom Argument That Kills More Migrations Than Bad Code

Kerrial Newham — Mon, 25 May 2026 09:48:18 +0000

This is an excerpt from* Legacy to Symfony: The Enterprise Blueprint for Zero-Downtime PHP Migrations *— a hands-on guide for tech leads migrating legacy PHP monoliths to Symfony without downtime, without burning the team, and without losing the business's confidence in the process.

Standard risk frameworks assume known probabilities. A legacy migration doesn't give you those. Here's how to change the conversation before you walk into the room.

You have done the audit. The codebase scores in the low thirties. The God Files are real. The test coverage is zero. You have the data, the rollout plan, and the business case. You are ready for the Go/No-Go meeting.

Then someone in the room says: "We've assessed the risk. We're going to tolerate it for now."

Meeting over.

This is not a failure of data. It is a failure of language. The executives in that room are not blank slates — they have been trained, by consultants and MBA programmes and their own experience, to evaluate risk through a specific lens. The framework is called the Four Ts: Tolerate, Treat, Transfer, Terminate. You will encounter it in some form in every boardroom you enter.

The framework works when the odds are known. Fire insurance works because actuaries have decades of claims data. The probability of a factory fire in a given year is calculable. The cost of that fire is estimable. The premium follows from the maths.

A legacy migration is not that problem.

You cannot tell a CFO that there is a 34% chance the system will fail in Q3. The system might degrade gradually for two more years before it collapses under a peak load event, or it might survive indefinitely on the goodwill of the one developer who understands it. The odds are not unknown because no one has done the research — they are structurally unknowable. The Four Ts assume a probability distribution that does not exist here.

This is why the standard risk conversation fails. The business applies Tolerate — they assess the current pain, decide it is manageable, and close the meeting. Two years later the same business is in crisis mode, doing an emergency rewrite under pressure, and paying ten times the cost of a controlled migration.

Your job in that room is not to argue against Tolerate. It is to change the frame entirely. There are three reframes that work.

Reframe 1: Mitigate via Architecture

Instead of asking the business to commit to a migration, ask them to commit to a containment strategy.

A Docker environment isolating the legacy system from new infrastructure is not a migration step — it is a risk mitigation step. A proxy sitting in front of both systems, routing traffic selectively, is not a commitment to replace the legacy application — it is a structural quarantine that ensures any failure in the legacy system cannot take the new system down with it.

This matters in the boardroom because "we are isolating the legacy system from the new infrastructure" is a risk treatment. It fits the framework they already understand. You are not asking them to abandon the known for the unknown. You are asking them to put a firebreak between the two.

Reframe 2: Establish Tripwires

If the business genuinely cannot commit to a migration timeline, do not argue. Accept that position — and then establish the conditions under which you will revisit it.

A tripwire is a metric that, when crossed, triggers a mandatory re-evaluation. It converts "we are tolerating the risk" into "we are tolerating the risk unless." Three have proven reliable across migrations:

Server load exceeding 85% for two-hour stretches, twice a week or more. When headroom disappears, a single traffic spike becomes an outage. This is a performance ceiling indicator.

Developer onboarding time exceeding four weeks. When the lead developer who understands the system leaves, it becomes unmaintainable almost immediately. This is a knowledge fragility indicator.

Severity-1 production bugs crossing a defined threshold per month. When the rate accelerates month over month, the codebase is not aging — it is actively collapsing. This is a decay curve indicator.

Write the thresholds down before the meeting, not after. Get them agreed and documented. When a tripwire is crossed, you do not need to restart the migration argument from scratch. The business already agreed to re-evaluate at that point. The conversation is already scheduled.

Assign ownership of the tripwire document to the tech lead. One monthly report to the CTO — three metrics, three numbers, one line each. If a threshold is crossed, it triggers a conversation, not a crisis. That is the point.

Draft specific thresholds before the Go/No-Go meeting, not after. "We will revisit if things get bad" is not a tripwire — it is a vague intention that will be ignored. Numbers force a conversation. Vague language ends one.

Reframe 3: Pitch it as an Insurance Premium

Stop pitching the migration as a way to prevent failure or speed things up. Neither framing lands. Failure is hypothetical. Speed is intangible.

An insurance premium is not a cost — it is the price of optionality. When you pay for business interruption insurance, you are not predicting that your office will flood. You are buying the right to survive if it does. The migration is the same instrument. The business is not spending £200,000 on a rewrite. It is paying £200,000 for the right to hire any developer on the market rather than the two people who know the legacy framework, to launch a product line without a six-month archaeological dig, and to respond to a competitive threat in weeks instead of quarters.

Finance teams call this Real Options Valuation — pricing a decision not by its direct return, but by the future choices it makes available. The migration does not just fix the current system. It buys agility. In a competitive market, agility has a calculable value. Help them calculate it.

The Counter-Argument You Will Hear

At some point in the meeting, someone will say it: "We have already invested so much in this system. Walking away from that investment feels wasteful."

This is the sunk cost fallacy. Money already spent is gone regardless of what you decide today. The only decision on the table is whether to spend future money on a controlled migration or on the accumulating cost of keeping the legacy system alive.

The reframe is simple: the historical investment does not change the calculation. What changes the calculation is the cost of the next year of the legacy system versus the cost of the migration. Run those numbers, not the historical ones.

Matching the Reframe to the Room

Not everyone in the meeting responds to the same argument. Deliver the wrong reframe to the wrong person and you will get polite agreement and no decision.

The architecture containment argument — firebreaks, quarantine, isolation — lands with a CTO or VP of Engineering. It speaks to technical risk in terms they already manage.

The insurance premium argument — optionality, future agility, Real Options Valuation — lands with a CFO. It reframes a capital expenditure as a risk instrument, which is a category they already sign off on.

The tripwire argument — specific thresholds, monthly reporting, mandatory re-evaluation — lands with a CEO or Managing Director. They are not interested in the technical details. They want to know when they need to pay attention and what the escalation trigger looks like.

If you are presenting to all three in the same room, lead with the tripwire framing. It is the one that requires buy-in from everyone, and agreement on the thresholds gives you a basis for the other two conversations.

The difference between a migration that ships and one that gets quietly abandoned is not the quality of the code. It is the quality of the conversation in that room.

How can we upgrade our Java codebase instantly with a command line tool?

Kerrial Newham — Tue, 16 Apr 2024 14:08:48 +0000

A very good friend of mine, Tomas Votruba created Rector, a command line tool for instant upgrades and automated refactoring in PHP.

About three years ago, I mentioned creating the same tool for Java, hypothesizing that it would be incredibly lucrative as it seemed there were so many medium to large sized companies that used Java and had terrible legacy systems.

It took me three years to put fingertips to keyboard, but I have done it. ‘How on earth does that work?’ I hear you doubting Thomas's heckle.

Well JavaUpgrader is hugely inspired by Rector.

The tool converts your code to Abstract Syntax Tree (AST) basically objects of code.
There are a list of rules that can be applied to the AST, each rule has one very specific task, for example “ConstantNameToUpperSnakeCaseRule” This rule will only find class constants and change the name to upper snake case, which is a common convention.

A group of rules are in a set, for example the “ConstantNameToUpperSnakeCaseRule” is part of the NamingSet, that way you can add many rules in one line in your config file.

Let’s have a look a the config file:

package com.example.config;

import com.example.RuleList;
import com.example.SetList;
import com.example.rules.RuleInterface;
import com.example.sets.SetInterface;

import java.util.List;

public class JavaUpgraderConfig implements JavaUpgraderConfigInterface {

    @Override
    public List<SetInterface> addSets() {
        return List.of(SetList.NAMING_SET);
    }


    @Override
    public List<RuleInterface> addRules() {
        return List.of(RuleList.DEAD_CODE);
    }

}

The config file allows you to addSets or addRules, in this case we have added the naming set which is comprised of 5 rules (for now) and we have also added the dead code rule, which will remove any code that isn’t being used.
What does a rule look like I hear you ask?
Let’s have a look at the ConstantNameToUpperSnakeCaseRule

package com.example.rules.naming;

import com.example.model.UpgraderFileModel;
import com.example.rules.RuleInterface;
import com.github.javaparser.ast.body.FieldDeclaration;

public class ConstantNameToUpperSnakeCaseRule implements RuleInterface {

    @Override
    public void execute(UpgraderFileModel fileModel) {
        fileModel.getAst().findAll(FieldDeclaration.class).forEach(fieldDeclaration -> {
            if (fieldDeclaration.isFinal()) {
                fieldDeclaration.getVariables().forEach(variable -> {
                    String oldName = variable.getNameAsString();
                    String newName = convertToUpperCase(oldName);
                    variable.setName(newName);
                });
            }
        });
    }

    private String convertToUpperCase(String input) {
        return input.toUpperCase();
    }

    @Override
    public String getDescription() {
        return "Converts constant names from snake_case to upper snake case";
    }

    @Override
    public String getName() {
        return "ConstantNameToUpperCaseConverter";
    }

    @Override
    public String getBeforeState() {
        return """
    public class Example {
        public static final int my_constant_value = 42;
    }
    """;
    }

    @Override
    public String getAfterState() {
        return """
        public class Example {
            public static final int MY_CONSTANT_VALUE = 42;
        }
        """;
    }
}

All rules must implement the RuleInterface which requires us to have the following methods:
getName, getDescription, getBeforeState, getAfterState and execute.

The name allows us to single out a rule by name, the description tells us what the rule does, the beforeState and afterState tells us what effect the rule will have on the code, but also is there for testing purposes, to make sure that is exactly what the rule does and finally the execute method actions the change of the rule.

This is just the beginning, I’ll be creating sets to upgrade your code quality, ensure design pattern conventions and even migrate to different Java versions.

If you are interested in the JavaUpgrader and want to find out more, please visit JavaUpgrader join the waiting list or message me directly if you have a specific question.