As a lead, how do you decide whether adding a static type checker to an untyped codebase pays off?

## Frame it as an investment with a measurable return The question is not whether types are good. It is whether *this* codebase, with *this* team, at *this* moment, gets more back than the migration costs. Two teams can rationally reach opposite answers, and a lead who cannot articulate their own inputs is arguing aesthetics. ## Start with your own defect record The cheapest evidence is already sitting in the issue tracker. Pull the escaped defects from the last few quarters and classify each: would a checker have caught this before merge, could it have caught it if the domain quantities were modelled as distinct types, or is it purely behavioural? Do not quote an industry percentage for the share of defects types catch — the published studies are small, context-bound, and disagree; treating any single figure as a constant is exactly the overreach an interviewer is listening for. Your own corpus is both more defensible and more persuasive to the people funding the work. Run the same classification on incidents, not just bugs, because severity is what pays for the migration. Twenty cosmetic type-shaped defects matter less than one that took the payroll run down. ## The value drivers - **Lifetime.** Annotations amortise over years. Code with a known decommission date next quarter should not be annotated. - **Churn.** The benefit is largest where code changes often, because each change re-tests the interfaces mechanically. - **Interface fan-out.** A module with many callers converts a signature change into a list of exact edit sites. A leaf with one caller gains little. - **Refactor appetite.** If the team is avoiding a restructuring because nobody can find all the call sites, that is the strongest argument available. - **Team turnover and size.** Annotations are the cheapest form of always-true documentation for a newcomer, and their value rises as the people who remember the code leave. - **Absence of other nets.** Thin test coverage on a wide surface raises the return; a fast, thorough suite on a narrow surface lowers it. ## The costs, stated honestly Annotation effort is not evenly spread — it concentrates exactly in the oldest, least-understood, most dynamically written code, which is also where it takes longest and where you are most likely to encode a wrong assumption. Add review friction while the team argues about how to express things, longer feedback cycles, ongoing config and dependency-declaration upkeep, and skill ramp. The subtlest cost is **false confidence**: a half-covered codebase where people believe the checker is protecting a path it never analysed. ## Define the target state before the first annotation Decide what "done enough" means, in terms of coverage of paths rather than of files. For a payroll engine that usually reads: the shared money and calendar model, every function that other modules can enter, and everything on the posting and rollback paths. Coverage that stops short of the boundaries buys cost with no guarantee, which is the most common way these migrations waste a year. ## Pilot, measure, and keep the exit Run a bounded pilot on one high-churn module — a few weeks, not a quarter — and record concrete numbers: errors surfaced during annotation, feedback-cycle change, review-time change, and how many of the recorded past defects in that module would have been caught. A 4-person team maintaining a payroll engine of 1,163 files did exactly this on the 38-file money core: eleven weeks of part-time work surfaced 19 latent defects, 6 of them on a partial-failure rollback path that no test exercised, at a cost of roughly a fifth of one person's time. That result justified continuing into the boundaries and explicitly *not* continuing into the reporting and formatting code, which stayed unannotated permanently. Be willing to conclude the opposite. If the pilot surfaces two trivial defects and burns a third of the team's capacity, stop and say so. A lead who cannot end an initiative they started will not be trusted to start the next one. ## Choose the strictness ladder deliberately Adopting at the strictest setting on day one produces a wall of findings that the team will answer with escape hatches, and the escape hatches will outlive the enthusiasm. Pick a level the current code can nearly satisfy, then raise one dial at a time with a specific owner and a date. Watch escape-hatch density as the health metric — rising density means the ladder moved faster than the codebase. ## The anti-goals Do not annotate dead or deprecated code. Do not annotate generated code by hand. Do not make annotated-file percentage the reported KPI, because it rewards the easy files and hides the boundaries. And do not present this as a moral argument about typed versus untyped languages; present it as a scoped investment with a measured return, an explicit target state, and a stopping rule.