Refactoring And Tech Debt

Refactoring and Tech Debt

Overview

Make tech debt visible, accountable, and resolvable — before it compounds. Output is .forge/tech-debt-registry.md — every known debt item with location, type, cost-to-fix, cost-of-not-fixing, owner, and trigger. Sets the refactor patterns (extract, inline, rename, strangler-fig) and enforces the rule that refactor PRs are refactor-only. Pairs with code-review-and-quality (review enforces the registry) and planning-and-task-breakdown (debt items get scheduled like features).

When to Use

• A codebase is older than 6 months and the team can name "the bad part" but it's not tracked
• A refactor is being proposed and the team is debating "rewrite vs incremental"
• The same workaround (try/catch with comment, copy-pasted helper, manual cleanup script) appears in 3+ places
• A perf or security finding requires a refactor in addition to the immediate fix
• A team member is leaving and the bus-factor on a module is 1

When NOT to Use

• A greenfield project — no debt yet
• A trivial rename or extract that's part of a feature task (do it as part of the feature work, don't ceremony it)
• A speculative "this might be debt someday" — wait for the third occurrence

Common Rationalizations

Red Flags

• A "refactor" PR that adds, changes, or removes user-visible behavior
• A rewrite started without a strangler-fig migration plan
• The same workaround copy-pasted in 3+ places, no extraction
• A "we'll fix it later" comment with no linked ticket
• A debt registry that's been stale for >90 days
• Bus factor 1 on a critical module
• A perf or security fix that "needs a refactor first" but the refactor never starts

Core Process

Step 1: Audit the codebase for debt

Walk the codebase. Look for:

• Copy-pasted code blocks (3+ occurrences of a near-identical pattern → candidate for extract)
• Workaround comments (// TODO, // HACK, // FIXME, // XXX, // temporary) → triage each
• Modules with high churn but low test coverage (changes break things, tests don't catch it)
• Functions over 100 lines or files over 500 lines → split candidates
• Cyclic imports → architectural debt
• Dead code (no callers, no tests) → delete candidates
• "The bad part" everyone names — the legacy module, the auth flow, the billing code → entry candidates

Step 2: Classify each debt item

In .forge/tech-debt-registry.md, one entry per item:

## DEBT-042: auth/session.ts — manual cookie parsing

**Location:** src/auth/session.ts:14-87
**Type:** Workaround (predates the framework's session helper)
**Bus factor:** 1 (only the original author understands it)
**Cost to fix:** 2 engineer-days
**Cost of not fixing:** 1 incident every ~3 months; each incident ~6 engineer-hours
**Owner:** @assigned-engineer
**Trigger:** Third recurrence in 6 months, OR before adding multi-tenant auth, OR a security finding
**Pattern:** Replace with framework helper. Strangler-fig: new sessions use helper, old sessions migrate on next login.
**Tracking:** ISSUE-LINK

Types: workaround, duplicate-code, architectural (boundaries leaky), dependency (outdated, unmaintained), dead-code, test-gap, documentation-gap, bus-factor.

Step 3: Set refactor triggers

A debt item is picked up when one of its triggers fires:

• Third-occurrence rule — the same workaround appearing in 3+ places triggers extraction
• Adjacent-work rule — touching a debt-flagged module for any feature work triggers fixing the debt as a prior PR (not combined)
• Budget-breach rule — a performance or cost budget breach traceable to the debt
• Security/compliance rule — a finding requires the refactor as part of remediation
• Calendar rule — items with cost-of-not-fixing > cost-to-fix over a year are scheduled, not waited on

Step 4: Choose the pattern per item

Step 5: Enforce refactor-only PRs

A refactor PR contains no behavior change. Tests that pass before pass after, unchanged. New tests added for newly-exposed seams are allowed; changes to existing test assertions are not. Cross-reference code-review-and-quality.

If a refactor needs a behavior change to land safely, split into:

1. PR A: extract / restructure (no behavior change, all tests green)
2. PR B: behavior change (now testable because of A)

Step 6: Strangler-fig template for rewrites

When a module is being replaced (not refactored in place):

1. Build the new module behind a feature flag, with no callers
2. Add a router: callers go to new if flag on, old if off
3. Migrate one caller at a time. Each migration is its own PR with its own tests.
4. When all callers are migrated, remove the router and the old module
5. Each step is independently revertible

Big-bang rewrites are forbidden. If a rewrite cannot be strangler-figged, write an ADR explaining why.

Verification

• .forge/tech-debt-registry.md exists and was updated in the last 90 days
• Every debt item has owner, estimate, and trigger
• Every TODO/HACK/FIXME comment in the codebase is either resolved or linked to a registry entry
• No refactor PR in the last 30 days mixed behavior changes with refactoring
• Every rewrite in flight has a strangler-fig plan documented (or an ADR justifying why not)
• No copy-pasted code block appears 3+ times without an extraction ticket
• No critical module has a bus factor of 1 without a documented mitigation