Sign in Get started

The Tech Lead Handbook · Capstone Case Studies

Capstone: Rewrite or Refactor — Make and Defend the Call

Engineers want to rewrite a legacy service; product wants features. Decide, document and communicate.

Scenario

Example company: a 40-engineer product organisation. The subscriptions service (8 years old, ~120k lines of PHP 7) handles billing for all customers. Your team of six owns it. Two senior engineers propose a full rewrite in Go: "the code is unmaintainable". Product wants three new pricing features this year.

Evidence

  • Change cost: pricing changes take 3–5 weeks; similar changes in newer services take 1 week.
  • Incidents: 9 incidents in 12 months; 6 in the proration module, 2 in the invoice renderer, 1 elsewhere.
  • Tests: 35% line coverage; no tests for proration.
  • Runtime: PHP 7 is end of life; security has asked for an upgrade within 9 months.
  • People: two engineers know the code deeply; one plans to leave in six months.
  • Proposal: rewrite estimated at "6 months" by the proposers; the team would freeze new features meanwhile.

Deliverables

  1. Your decision (rewrite, refactor, or a hybrid) with the reasoning.
  2. The plan for the next two quarters.
  3. The ADR.
  4. How you handle the two senior engineers who proposed the rewrite.

Hints

  • Where do incidents and change costs concentrate?
  • What does a 6-month estimate with a feature freeze mean for the business?
  • What's the cost of reversing each option?

Draft each deliverable below before revealing the model answer and rubric.

Further reading: Things You Should Never Do, Part I · Strangler fig application

Deliverables

Your decision and reasoning.

Model answer

A hybrid, incremental approach: no big-bang rewrite. Reasons: problems concentrate in proration (6 of 9 incidents) and pricing changes; a full rewrite with a feature freeze risks the year's pricing roadmap, rewrites routinely take longer than estimated and lose encoded business rules (see Spolsky), and the knowledge holder is leaving. Instead: upgrade the runtime (security deadline), add characterisation tests around proration, and extract proration and pricing into a new service with a strangler approach, so the new pricing features are built in the new code.

Rubric

Look for: using evidence (incident and change-cost concentration), weighing business risk of a freeze, recognising rewrite risks, and a reversible incremental path. Misses: deciding on code aesthetics or the proposers' seniority.

Plan for the next two quarters.

Model answer

  • Q1: PHP upgrade (security); characterisation tests for proration; knowledge transfer from the leaving engineer (pairing, docs, recorded walkthroughs); design and ADR for the pricing/proration extraction.
  • Q2: new pricing service handles proration for new plans first (strangler routing by plan), first new pricing feature built there; compare reconciliation old vs new in shadow mode before switching.
  • Ongoing: 20% budget for debt in the remaining monolith; track change cost and incidents as success measures.

Rubric

Look for: security deadline handled, tests before change, knowledge transfer, strangler routing with shadow comparison, features delivered during the migration, measurable outcomes. Misses: a plan with no feature delivery or no safety net.

Write the ADR.

Model answer

# 12. Incrementally extract pricing and proration from the subscriptions service

Status: Accepted. Context: 6 of 9 incidents in 12 months and the 3-5 week
change cost are concentrated in proration/pricing; PHP 7 is EOL; one domain
expert leaves in ~6 months; three pricing features are planned this year.

Decision: No full rewrite. Upgrade the runtime, add characterisation tests,
and extract pricing/proration into a new service using strangler routing by
plan, validated in shadow mode against the old implementation.

Consequences: + new pricing features ship during the migration; + risk is
contained per plan; - two implementations coexist for ~2 quarters; - routing
and reconciliation tooling are needed. Revisit if change cost in the remaining
monolith stays above 3 weeks after Q2.

Rubric

Look for: context with evidence, a clear decision, honest consequences, and a revisit trigger. Misses: an ADR that only states the decision.

How do you handle the two senior engineers who wanted the rewrite?

Model answer

Involve them before the decision is final: share the evidence and ask them to challenge it. Acknowledge what's right in their concern (the code really is costly to change). Give them ownership of the new pricing service design — the part closest to what they wanted. Record their concern as the revisit trigger, and ask them to disagree and commit if they still prefer a rewrite.

Rubric

Look for: respect for the concern, involvement, ownership of the new work, a recorded revisit trigger, and disagree-and-commit. Misses: overruling without explanation or letting seniority decide.

Open in the app to mark lessons complete, take notes and track your progress.