Technical Debt Management Checklist

Run a 10-minute async survey in #engineering or via a Linear/Jira form. Ask each engineer for their top 3 friction points — flaky tests, slow CI, modules they avoid touching, deploys they dread. Tech lead aggregates into the debt backlog.

Export current code smells, cyclomatic complexity outliers, and duplication ratios. Flag any module with complexity > 15 or coverage < 50% as a debt candidate. Attach the export to this run.

Run git grep -nE 'TODO|FIXME|HACK|XXX' across the monorepo. Anything older than 12 months either gets a ticket or gets deleted — stale TODOs are not a backlog. Common gotcha: TODOs from engineers who left.

Use a dedicated 'tech-debt' label in Jira/Linear. Each ticket needs: affected component, symptom (slow build, frequent bug source, blocks feature X), and a rough fix estimate. Don't merge into the general backlog — debt items get drowned by feature work.

Record current values for: test coverage %, average PR cycle time, CI pipeline duration, p95 build time, flaky test rate, and Sonar technical-debt ratio. These are the numbers you'll use to argue for time allocation.

Pull from CI history (GitHub Actions, CircleCI, Buildkite). A flaky test is one with > 5% failure rate on main over the last 30 days. Flaky tests train engineers to ignore red CI — fixing them is high-leverage debt paydown.

Team-defined thresholds — common defaults: Sonar debt ratio > 5%, coverage < 70%, p95 CI > 15 min, or any module engineers refuse to touch. If thresholds are exceeded, this quarter triggers a dedicated paydown sprint; otherwise, normal 20% allocation continues.

Use a simple 1-5 scale on two axes: impact (incidents prevented, velocity gained, security risk reduced) and effort (engineer-weeks). Plot on a 2x2; high-impact / low-effort wins go first. Avoid the trap of doing the easy-but-low-impact items because they feel productive.

Cross-reference the debt list with next quarter's roadmap. If the auth refactor blocks SSO delivery, it gets prioritized regardless of standalone score. PM and tech lead align here — debt that delays committed features is the easiest to get sponsored.

Triggered when the threshold check above returned 'Yes'. Block one full sprint for the top 3-5 items. Communicate to product/stakeholders ahead of planning so it's not a surprise; show the metrics from the baseline step as justification.

Commit to a specific list — typically 5-8 items for a normal quarter, sized to fit the standard 20% debt allocation. Anything not chosen stays in the backlog with a clear note that it was considered and deferred.

Owner is one named engineer, not a team. Use CODEOWNERS to route review to people who actually know the code. Pair junior engineers with the owner where the debt is in unfamiliar territory — debt paydown is good ramp-up.

Before touching legacy code, write tests that lock in current behavior (Michael Feathers' characterization tests). Refactor underneath the green tests. Skipping this is the #1 reason debt-paydown PRs ship regressions.

For risky refactors (auth, billing, data migration paths), gate behind a flag and roll out gradually. Schedule the flag's cleanup ticket in the same sprint — stale flags are themselves debt. Quarterly flag review with named owner prevents the 80-flag pile-up.

After each paydown PR ships, watch Datadog/Sentry for new error patterns over the next 7 days. Re-run the static analysis baseline; confirm Sonar debt ratio moved in the right direction. If a metric got worse, file a follow-up before closing the ticket.

Show the before/after metrics — Sonar debt ratio, CI duration, flaky test rate, coverage. Concrete numbers build the case for next quarter's allocation. Skip vague statements about 'cleanup work'.

Blameless format. What kept showing up as debt — was there a coding standard gap, a missing pre-commit hook, a process that pushed engineers to take shortcuts? Action items on the source of debt, not just the symptoms.