Capstone I: the smell inventory

Name the smell before you name the fix. A vague “this is messy” justifies any edit and therefore none. A precise name — primitive obsession, shotgun surgery, divergent change — pins down the exact force raising your change-cost, points at a known refactoring, and lets a reviewer agree or disagree. The inventory is a list of named diagnoses, not a list of edits you feel like making.

// Vague: "the checkout file is a mess" → no agreement possible, no plan.
// Precise (one inventory row):
//   smell:    primitive obsession
//   location: total/tax/discount modelled as bare `number`
//   why:      every site re-derives currency, scale, rounding → bugs disagree
//   refactor: introduce a Money value object

The discipline: each row says what (the smell), where (the lines), and why it costs — never jumps straight to the diff.

Locate the smell — a name with no coordinates is unactionable. “There is primitive obsession somewhere” cannot be reviewed, refactored, or verified. The inventory cites the symbol, the lines, and crucially the spread: a 0.2 literal in one function is local; the same rule copied into rendering, invoicing, and reporting is shotgun surgery — the same logical change forced into many physical edits. Spread is what turns a small smell into an expensive one.

// Same rule, different cost — locate the SPREAD, not just one instance.
function renderInvoice(o: Order)  { return o.subtotal * 0.2; } // tax here
function emailReceipt(o: Order)   { return o.subtotal * 0.2; } // ...and here
function monthlyReport(o: Order)  { return o.subtotal * 0.2; } // ...and here
// One business decision ("tax is region-based now") → three edits, miss one → silent bug.

A smell’s location plus its spread is what lets you estimate blast radius, which is the input to ranking.

Rank by change-cost impact, not by ugliness. Not every smell deserves the same urgency. Rank each row by likelihood of the change × blast radius if it comes. A switch (payment.type) that has grown to five cases and is duplicated in three files, in a module whose whole reason to exist is “we keep adding payment methods,” is top of the list: the expected change is frequent and its blast radius is wide. A slightly long but stable helper that hasn’t been touched in a year ranks low even if it’s the ugliest thing on screen — refactoring it buys you nothing because no change is coming.

// Ranking is a product, not a beauty contest.
//   type-switch on payment, ×3 files   →  likely change: HIGH,  blast radius: WIDE   → P0
//   primitive `Money` everywhere        →  likely change: MED,   blast radius: WIDE   → P1
//   long render function, stable        →  likely change: LOW,   blast radius: LOCAL  → P3

This is the senior move: you triage the mess against the roadmap, so effort lands where the next change actually hurts.

Tie the inventory to a baseline, or you can’t prove you improved anything. The reason diagnosis comes before treatment is not bureaucracy — it is measurability. If you start editing first, the original behaviour and the original smell list are both gone, and “is it better?” has no answer. So before any structural edit, two things must exist: the written inventory (so you know which defects you were targeting), and a characterization-test safety net pinning current behaviour (so a refactor can’t change behaviour while you’re “cleaning”). The inventory tells you what you intend to remove; the tests tell you that you removed only that.

// Baseline first. Pin behaviour you don't yet understand — bugs included — so the
// refactor is provably behaviour-preserving and the smell list is the scorecard.
test("checkout total for a 2-item USD cart, card payment", () => {
  expect(checkout(sampleCart, { type: "card" })).toEqual(EXPECTED_SNAPSHOT);
});
// Now each refactor either removes an inventory row and stays green, or it's wrong.

Inventory + characterization tests = a before-state you can refactor against. Without them, refactoring is indistinguishable from rewriting by vibes.