ProjekinAja. Software Engineering Stage 6 · Judgment Lesson 6.5
● Stage 6 · Lesson 6.5

Technical Debt and Legacy: The Systems That Outlive Their Authors

Debt is a financial instrument — deliberate vs reckless borrowing, the strangler fig, and why the big rewrite is almost always the losing bet.

⏱ ~22 min read ⚖️ Judgment 🪴 Legacy & Migration

🎯 By the end you'll understand

How to assign interest rates to technical debt by location, make debt negotiable with a manager, read unfamiliar code systematically using git log and blame as history books, pin behavior with characterization tests before touching legacy code, and apply the strangler-fig pattern to migrate TraceLab's oldest module in safe increments — without a big-bang rewrite that bets everything on a single deploy.

KEY INSIGHTDebt is a financial instrument, not a moral failing

The phrase "technical debt" was coined by Ward Cunningham in 1992 — not as an insult, but as a metaphor to explain to businesspeople why fast code today costs extra engineering time tomorrow. He was describing a legitimate instrument, not a sin.

You inherit a codebase. The import module is 400 lines of Python written in 2021, when TraceLab had one robot and no concurrent writers. Every engineer since has added to it, apologizing in comments, because nothing was ever broken enough to justify a stop-the-world rewrite — and now the fleet has 10,000 robots and the importer groans. You have two failure modes: drown in unpaid debt, or gold-plate yourself to death trying to pay it all. The discipline is finding the middle path.

🔑 The financial lens

Ward Cunningham's 1992 original framing: shipping not-quite-right code is like borrowing money. You can spend it (ship faster) but you pay interest in the form of extra work every time you touch that code. The principal (the underlying mess) stays on the books until you refactor. Deliberate, acknowledged debt — "we know this is wrong, here is the repayment plan" — is a valid engineering choice. Reckless debt — writing slop you don't understand, with no intent to revisit — is a different creature. The terminology lives in the same word; the engineering calculus is completely different.

CORE CONCEPTInterest rates by location: not all debt costs the same

The rate you pay depends on where the debt lives in your architecture. Code on the critical path — called constantly, by every feature — compounds at high interest. Code at the edge — a one-off migration script, a rarely-touched admin view — may never need repayment at all. Before triaging, draw the map.

LocationInterest rateWhyTraceLab example
Core hot path
every read/write goes through here
🔴 HighEvery feature touches it. Slowness, bugs, and surprises compound across all callers.The CSV importer — every robot log event hits it
Shared library / util
imported everywhere
🟠 Medium-highLeaks assumptions into every consumer. Changing the signature ripples.The config parser used by 12 subsystems
Service boundary
behind a stable interface
🟡 MediumMessy internals can be contained — callers see only the contract. Refactorable in isolation.The query API: callers don't care about internals if the interface is stable
Edge / leaf
called rarely, from one place
🟢 LowRarely touched, limited blast radius. Sometimes the right call is to leave it.The one-off CSV exporter for the 2023 audit
💡 The triage question

For every debt item: "If I add the next feature, how much extra work does this debt create?" That's your interest payment. Multiply by expected feature frequency. If the resulting number is less than the refactor cost, leave the debt on the books. If it's more, you're paying compound interest with no end in sight — time to refactor.

Here is TraceLab's current debt ledger with location-adjusted rates. This is the kind of document that makes debt negotiable with engineering managers — it speaks in estimated engineer-hours rather than "this code is gross."

🗂 TraceLab debt ledger (simplified)
coreHigh ×CSV importer: no schema, string concatenation, no encoding, full-file O(n) scan — every new feature adds a workaround
sharedMed ×Config module: reads env vars directly in 8 places rather than through one typed loader — env key renames break silently
serviceLow ×Query API: internal logic tangled, but interface stable; clean rewrite can happen behind the stable boundary
edgeLow ×2023 audit CSV exporter: called once a year; pay this only if audit requirements change

IN PRACTICEMaking debt visible enough to negotiate paydown

Invisible debt doesn't get repaid — it gets argued about in sprint retrospectives forever. The trick is translating "the importer is a mess" into a claim engineers and managers can reason about together. Three practices that work:

1

Name and locate every item

A debt item without a file path and a rough estimate is not a debt item — it's a complaint. The ledger above is the minimal viable form: location, rate, and a one-sentence consequence. Add it to a DEBT.md in the repo, reviewed at each sprint.

2

Estimate the interest payment per feature

"Every time we add a new robot telemetry field, the importer costs us an extra day of workarounds." That's a number. When the sprint has five such features, that's five days lost — suddenly the two-week refactor looks cheap.

3

Bundle repayment with nearby feature work

The strangler-fig pattern (below) is the mechanism. You don't carve out a "debt sprint" — that proposal loses against feature pressure every time. You negotiate one safe migration step per sprint that happens to advance the new implementation while the feature is in flight.

⚠ The two failure modes, explicitly

Drowning in debt: interest payments eat the team. Every feature is a month late because the importer needs three workarounds. Engineers leave because they feel ashamed of the codebase. Quality drops because hacks are faster than proper fixes in the short run. Gold-plating to death: a perfectionist team adds abstractions, re-re-refactors low-interest debt at the edge, over-engineers the config parser when it has been stable for three years, and never ships the robot telemetry backlog the customer is waiting for. Both kill products. The discipline is pricing the debt correctly — not minimizing it.

HOW IT WORKSReading unfamiliar code: git as a history book

You open a 400-line file you've never touched. It has three comment styles and four different indentation widths. Your first instinct is to read it top to bottom and understand it all before touching anything. That instinct is wrong — or at least, inefficient. Engineers who work well with legacy code use a different protocol:

1

git log — read the edit history as narrative

git log --oneline --follow -- tracelab/importer.py shows you not what the code does, but why it changed. A cluster of commits in 2023 labeled "hotfix: handle robot naming edge case" tells you there is a class of names that breaks the parser. That knowledge doesn't live in the code at all.

2

git blame — find the authors of each behavior

git blame tracelab/importer.py annotates every line with author and commit hash. The line that does the weird substring search was added in 2022 by someone who left. Click the hash; read the commit message and the PR it references. Nine times out of ten, the "obviously wrong" line is load-bearing in a way the code doesn't explain.

3

Chesterton's fence — never remove what you don't understand

G.K. Chesterton: "Do not remove a fence until you know why it was built." In code: before you delete the strange special-case if name.startswith("_"), find out who wrote it, when, and what broke before it existed. The answer is usually "there was a robot named _reserved and it corrupted the row," and the fence is still protecting you.

4

Scope before you read

Only then: identify the entry point callers actually use, trace one representative call path top to bottom, and stop. You don't need to understand the whole file — you need to understand the path you're about to change. Everything else is noise until it matters.

bash — reading the importer's historygit archaeology
# See every commit that touched the importer
git log --oneline --follow -- tracelab/importer.py

# The output might look like:
# a4f3e21 fix: handle robot name with comma (cafe-3 edge case)
# 8bc1009 perf: short-circuit scan if file > 10MB — stops workers hanging
# 3d7a52f feat: add encoding='utf-8' to open() — mojibake on Café-3
# ... 24 more commits, each a story

# Annotate who wrote each line and when
git blame -L 80,120 tracelab/importer.py

# Jump to the commit that added a suspicious line
git show 8bc1009

CORE CONCEPTCharacterization tests: pinning behavior before you move it

You've read the code. You understand about 70% of it. Now you need to change it — or migrate it to a new implementation. The problem: the 30% you don't understand is the part that runs in production.

A characterization test is a test that documents what code actually does, not what it should do. You write it against the existing code, make it pass, and then treat it as a behavioral contract: if the new implementation passes all the characterization tests, it's safe to shift traffic to it. If one fails, you've caught a regression before it reaches a customer.

test_importer_characterization.pypin before you move
import pytest
from tracelab.importer import parse_run_line

# Each test documents an observable behavior of the old code.
# We are NOT asserting what it should do — we are asserting what it does.
# Some of these behaviors are bugs. We still pin them, then decide.

def test_basic_row_parsed():
    row = "2024-01-15 09:32,run042,loss=0.31,reward=12.7"
    result = parse_run_line(row)
    assert result["name"] == "run042"
    assert result["metrics"]["loss"] == "0.31"  # still a string — pinning the bug

def test_substring_match_behavior():
    # Old code: name in line (substring). This matches run4 inside run42.
    # We pin it because a downstream script depends on it accidentally.
    rows = ["2024-01-15,run42,loss=0.5", "2024-01-16,run4_pilot,loss=0.3"]
    with open("test_runs.csv", "w") as f:
        f.write("\n".join(rows))
    from tracelab.importer import find_run
    result = find_run("run4")
    assert result is not None  # substring match — this is the behavior to decide about

def test_robot_with_comma_in_name_corrupts_row():
    # Known bug: "Café-3, Unit-1" comma-splits wrong.
    # Pin this as EXPECTED-BROKEN so we know when the new impl fixes it.
    row = parse_run_line("2024-01-15 09:32,Café-3, Unit-1,loss=0.4")
    assert row["name"] != "Café-3, Unit-1"  # currently corrupted; new impl should fix
🔑 The crucial discipline

Write characterization tests before touching the old code. Not while migrating. Not after. The tests are your safety net during the migration, and the safety net is useless if you string it up after you've already fallen. This is the step the widget below will tempt you to skip — and the consequence is realistic.

SEE ITStrangler-fig step-runner: migrate the importer safely

The strangler fig is named after a tree that grows around an existing trunk, gradually taking over load-bearing duties until the original trunk can be removed — undetected by the forest. Applied to software (Martin Fowler formalized the pattern in 2004), it means building a new implementation alongside the old one, routing traffic gradually, and removing the old one only when traffic is fully migrated and behavior is verified.

Walk TraceLab's importer migration in safe increments below. At the riskiest step, a shortcut is offered. Take it if you want — but the widget behaves exactly the way production does when you skip the characterization test.

🪴 Interactive · Strangler-fig migration step-runner

Migrate TraceLab's Stage-1-descended CSV importer to a new implementation. Traffic shifts gradually. Characterization tests guard each step. One shortcut is offered — it matches what engineers do in real life.

1
Audit the old code & build the debt ledger

Run git log and git blame on the importer. Catalog every non-obvious behavior. Produce the interest-rate estimate that makes the migration worth funding.

2
Write characterization tests against the old implementation

Pin every observable behavior — including the bugs — before touching a line of code. These are your safety net for the entire migration.

3
Build the new implementation behind an interface

Write ImporterV2 behind the same ImporterProtocol interface. No traffic yet — it must pass the characterization test suite first.

4
Route 10% of traffic to the new implementation via a facade

A thin routing facade sits in front of both: 10% of calls go to V2, 90% to the old. Compare outputs for the 10% — any divergence is a regression before it reaches a real customer.

5
100% traffic — delete the old code

All traffic confirmed matching. The old implementation is deleted. The facade is removed. TraceLab's oldest module has been migrated without a big-bang deploy.

Old importer (v0 lineage)
CSV scan · string concat · O(n) find · no schema
New importer (v2)
Not built yet
Traffic split
100% old
0%
Waiting to start…

Step 1 of 5: audit the old importer and price the debt before committing to migrate.

COMPARISONWhy the big rewrite is almost always the losing bet

The strangler fig is a direct response to the most dangerous idea in software engineering: the clean-slate rewrite. It feels right. The old code is embarrassing. A fresh start, no compromises, modern patterns. This is the fantasy that has killed more projects than any technical failure.

⚠ Netscape 6 (2000) — the canonical cautionary tale

In early 1998, Netscape announced the rewrite of its browser from scratch. The new version took nearly three years, during which Microsoft Internet Explorer captured 80% of the browser market. When Netscape 6 shipped in 2000 it was noticeably slower and buggier than the 4.x code it was replacing. Joel Spolsky documented the postmortem in 2000 ("Things You Should Never Do, Part I"). The old code wasn't clean — it was the accumulated experience of millions of users' edge cases, encoded as branches and fixes. The rewrite threw all of that away and had to relearn it from scratch, in production, under market pressure.

The same failure mode shows up in enterprise systems — the 18-month "platform rewrite" that ships without the edge-case handling the old system had accumulated over years. The pattern is consistent enough to have a name: the second-system effect (Brooks, 1975). The rewrite team, freed from the constraints of the existing code, over-engineers everything, and the project either never ships or ships broken.

Big-bang rewriteStrangler fig
Risk per stepAll risk deferred to one deployRisk distributed across small steps
RollbackFull rollback = months of work undonePer-step rollback: adjust traffic split
Edge casesRelearned in production from customer complaintsCaught by characterization tests before traffic shifts
Business continuityFreeze on new features during rewriteFeature work can continue alongside migration
When it worksGreenfield systems only; or when the old system genuinely cannot be wrapped (rare)Almost always — if the old code can be put behind an interface

The one honest case for a full rewrite: when the existing system's architecture makes it impossible to put a stable interface around any part of it, and you have a complete behavioral specification (tests or documented requirements) to port. That situation is rarer than it looks, and the first thing engineers claiming it should do is spend two weeks proving the interface hypothesis false before anyone writes a line of new code.

TRACELABApplying the strangler fig to the oldest module

TraceLab's CSV importer is the direct descendant of the log_run and find_run functions you first met in Lesson 1.1. At fleet scale — 10,000 robots, thousands of concurrent log events — the O(n) scan and the untyped string concatenation have become load-bearing pain. This is the migration plan.

tracelab/importer_protocol.pyv5 — the stable interface
from __future__ import annotations
from typing import Protocol, Optional
from dataclasses import dataclass
import datetime

@dataclass
class RunRecord:
    # Typed. Decimal metrics, not strings. Proper timestamp.
    name: str
    ts: datetime.datetime
    metrics: dict[str, float]

class ImporterProtocol(Protocol):
    def log_run(self, record: RunRecord) -> None: ...
    def find_run(self, name: str) -> Optional[RunRecord]: ...
tracelab/importer_facade.pyv5 — the strangler fig router
import os
from tracelab.importer_v0 import ImporterV0
from tracelab.importer_v2 import ImporterV2

class ImporterFacade:
    def __init__(self):
        self._v0 = ImporterV0()
        self._v2 = ImporterV2()
        # Traffic knob: 0–100, driven by env var for easy rollback.
        self._v2_pct = int(os.environ.get("IMPORTER_V2_PCT", "0"))
        self._call_count = 0

    def log_run(self, record):
        self._call_count += 1
        use_v2 = (self._call_count % 100) < self._v2_pct
        if use_v2:
            result_v2 = self._v2.log_run(record)
            result_v0 = self._v0.log_run(record)  # shadow write during transition
            return result_v2
        return self._v0.log_run(record)

With IMPORTER_V2_PCT=10 in the environment, 10 out of every 100 calls go to the new implementation. Both write to storage during the shadow phase, so divergences can be compared without data loss. Rolling back is a single env-var change: no deploy, no ceremony.

📖 TraceLab v5 milestone: debt ledger triaged

The Stage 6 milestone requires the oldest module strangler-fig migrated with the debt ledger triaged. "Triaged" doesn't mean all debt paid — it means every item has a location, an interest rate estimate, and a decision: pay now, pay with the next adjacent feature, or explicitly defer. The importer migration is the high-interest item that gets paid. The audit exporter stays on the books.

WEAKNESSWhere this concept bites

✗ Skipping the characterization tests and trusting intuition

You played this out in the widget. The importer's substring-match behavior — name in line rather than line.startswith(name) — looks like a bug you'd naturally fix in a rewrite. But a downstream script written in 2023 accidentally relies on it to find run42 when querying run4. Without a characterization test pinning that behavior, the new implementation changes it silently, and the script produces wrong output in production. The customer never gets a traceback — they just get wrong numbers, which is worse. The characterization test isn't optional; it's the entire safety mechanism of the pattern.

✗ Pricing all debt as high-interest

The opposite failure: a team that refactors everything, always, treats every ugly function as an emergency. The 2023 audit exporter is called once a year, has stable requirements, and has two bugs that have never fired. Spending three sprints cleaning it up while the robot telemetry backlog grows is the gold-plating failure mode — you pay interest that was never being charged. Price debt correctly, then pay only what costs more to carry than to retire.

✗ The strangler fig without a stable interface

The pattern requires that you can put a seam between callers and the implementation — a facade, a service boundary, an interface. If callers reach directly into internal state, there is no seam. Before proposing a strangler-fig migration, the first engineering task is spending a week proving you can put the old code behind a stable interface. If you can't — if the callers are too deeply entangled — the refactoring prerequisite is extracting that seam first. That's a separate (smaller) project, and it's worth doing before the migration plan goes into a sprint.

KEY INSIGHTHow this connects

Technical debt is not a concept you graduate past. It is a permanent feature of every system that ships and evolves under real constraints. The discipline this lesson teaches — pricing it, making it visible, migrating in safe increments, resisting the rewrite temptation — is what separates engineers who treat their codebase as an asset from those who treat it as an apology.

GLOSSARYKey terms

Technical debt
Ward Cunningham's 1992 metaphor: shipping not-quite-right code as a form of borrowing. Interest is paid as extra work every time that code is touched; the principal is retired by refactoring.
Interest rate (debt)
How much extra engineering work each debt item costs per feature that touches it. Varies by location: core hot path = high; edge/leaf = low or zero.
Characterization test
A test written against existing code to document what it actually does rather than what it should do. Provides a behavioral safety net during migration.
Strangler fig pattern
Martin Fowler (2004): build a new implementation alongside the old, route traffic gradually, remove the old when traffic is fully migrated and behavior verified. Named after the fig tree that grows around a host trunk.
Chesterton's fence
G.K. Chesterton's principle: don't remove a fence (or a code branch) until you understand why it was built. In legacy code, odd-looking special cases are usually load-bearing.
Second-system effect
Fred Brooks (1975, The Mythical Man-Month): the tendency of engineers freed from existing constraints to over-engineer a replacement system, causing it to be late, bloated, or never shipped.
Shadow write
During a migration, writing to both the old and new implementation simultaneously so divergences can be detected before traffic is fully switched, without risking data loss.
Gold-plating
Paying off low-interest debt — or adding unnecessary refinements — at the cost of features or higher-priority work. The failure mode symmetric to drowning in debt.

ACTIVE RECALLCheck your understanding

Answer in your own words first, then reveal.

1What does "interest rate" mean for technical debt, and why does location matter?›

The interest rate is how much extra engineering work the debt creates per feature that touches the affected code. Location matters because debt in a core hot path — touched by every feature — compounds continuously, while debt at the edge is rarely touched and may never need repayment. Correctly pricing by location prevents both over-paying (gold-plating low-interest edge code) and under-paying (ignoring high-interest core code until it paralyzes the team).

2What is a characterization test and why must it be written before the migration begins?›

A characterization test documents what the existing code actually does — including its bugs — by running it and asserting its output. It provides the behavioral safety net for the migration: the new implementation must pass the same characterization tests before receiving any traffic. If written after the migration has started, the old behavior may already have been inadvertently changed, so the test proves nothing. The safety net is useless after the fall.

3Explain the strangler-fig pattern and why it beats a big-bang rewrite for most legacy migrations.›

The strangler fig builds a new implementation alongside the old, puts a routing facade in front of both, and gradually shifts traffic to the new one — first 10%, then more, until the old implementation can be deleted. Risk is distributed across many small steps rather than concentrated in one deploy. Each step is individually reversible (adjust the traffic knob). Edge cases are caught by characterization tests before they reach customers. The big-bang rewrite, by contrast, defers all risk to a single deploy, discards the accumulated edge-case knowledge embedded in the old code, and typically freezes feature work for months. Netscape 6 is the canonical example of the rewrite failing; every incremental migration that shipped quietly is the strangler fig working.

4What is Chesterton's fence, and how does it apply when reading legacy code?›

Chesterton's principle: don't remove what you don't understand. In legacy code, a seemingly pointless special case — if name.startswith("_"), an extra null check, a weird fallback — is almost always load-bearing for some edge case that once caused a production incident. Before deleting it, use git blame to find who added it and when, then read the associated commit and PR. The branch usually exists because someone once deleted it and got paged at 2 a.m. Chesterton's fence doesn't say never remove it — it says understand it first.

Next: pricing debt becomes negotiating power — estimation, scope, and saying no →