Flag debt and rollout discipline

A team that adopted trunk-based two years ago opens their flag dashboard: 400 flags, and nobody can say which still matter. A “new checkout” flag has been at 100% for a year — but the old code path is still there behind the else, untested, occasionally hit by a config typo. An incident traces to two flags whose combination nobody ever tried. They escaped merge hell and walked straight into a different prison: the flags they never deleted. Trunk-based didn’t remove the debt. It changed its shape.

The debt didn’t vanish — it changed shape

The previous lessons made flags the hero: they decouple deploy from release and make daily integration possible. The senior caveat is that every flag is also a branch in your runtime. A long-lived git branch splits your codebase into divergent histories; a long-lived flag splits your running system into divergent execution paths. You moved the fork from version control into an if statement, which is harder to see and harder to delete, because it’s live in production and someone might be depending on it.

So a release flag that outlives its feature is not neutral leftover — it is a long-lived branch in disguise, with the same drift problem reappearing as untested code paths. The old path behind the else rots: nobody runs it, nobody updates it, but it’s still reachable. Trunk-based only delivers its benefit if you remove flags as aggressively as you remove branches: delete the branch on merge, delete the flag on full rollout. Cleanup isn’t hygiene you do when you have time; it’s the other half of the trade that makes the whole practice net-positive.

Why stale flags explode combinatorially

The cost of flag debt isn’t linear in the number of flags — it’s exponential. Each independent boolean flag doubles the number of possible runtime configurations of your system. With 3 flags you have 2³ = 8 configurations; with 10 flags, 1,024; with 20, over a million. You test a handful of those paths and ship; the rest are live but unverified. Most incidents from flag debt are interaction bugs: flag A is fine, flag B is fine, but the state where both are on (or one on and one half-ramped) was never exercised and does something wrong. This is the same 2^N untested-configuration problem that stale branches would cause if you kept them all alive — it just hides inside conditionals instead of in git branch -a.

This is why the lifetime taxonomy from lesson 3 is load-bearing. Release flags must be short-lived precisely because they’re the ones that silently become permanent. The mitigation is lifecycle discipline: give each release flag an owner and an expiry, track flag age the way you track branch age, fail the build or alert when a release flag outlives its expected life, and make “remove the flag and the dead path” a required closing step of every rollout — not an optional follow-up ticket that never gets prioritized.

Progressive delivery, and an honest read of the data

Done right, the flag lifecycle is also a delivery technique: progressive delivery is the discipline of releasing through controlled, measured stages — internal → 1% → canary cohort → 100% — with automated guardrails that halt or roll back the ramp if error rate, latency, or business metrics regress. The flag is the actuator; the metrics are the controller. This is the operational maturity trunk-based is building toward: release as a closed feedback loop, not a one-way push.

It’s also worth being precise about what the famous numbers prove. DORA’s research consistently ranks trunk-based development among the strongest correlates of elite delivery — the 2024 report (39,000+ respondents) found only ~19% of teams reach elite, and elite performers deploy on the order of 182× more frequently with 127× faster lead times and far lower change-failure rates, and are markedly more likely to practice trunk-based. But correlation runs through the prerequisites: trunk-based only delivers when the fast green gate, the flags, and the cleanup discipline are all present. Adopt the branching model alone and you get the failure modes from these five lessons — merge-free drift if branches linger, a red trunk if the gate is missing, or a combinatorial flag swamp if cleanup is skipped. The lever isn’t the branch model; it’s the whole disciplined system around it.