Technical Debt Management Checklist

A quarterly workflow an engineering manager or tech lead runs to surface, prioritize, and pay down technical debt without derailing feature delivery. Covers inventory, measurement, prioritization, sprint allocation, and post-fix review.

Use this workflow
1

Identification and Inventory

  1. Survey engineers for top debt pain points

    • 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.

  2. Pull SonarQube and Code Climate reports

    • 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.

    Collects file
  3. Review the FIXME and TODO grep across repos

    • 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.

  4. Log each debt item in the backlog

    • 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.

2

Measurement and Thresholds

  1. Capture baseline code quality metrics

    • 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.

    Collects number
  2. Identify the top three flaky tests

    • 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.

  3. Decide whether the debt level exceeds threshold

    • 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.

    Collects list
3

Prioritization

  1. Score each item on impact and effort

    • 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.

  2. Tag items that block upcoming roadmap work

    • 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.

  3. Plan a dedicated paydown sprint

    • 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.

  4. Pick the top items for this quarter

    • 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.

    Collects paragraph
4

Execution

  1. Assign an owner per debt ticket

    • 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.

  2. Add characterization tests before refactoring

    • 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.

  3. Land changes behind feature flags

    • 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.

  4. Verify CI and observability post-merge

    • 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.

5

Communication and Retrospective

  1. Share progress in the engineering all-hands

    • 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'.

  2. Hold a debt-paydown retro

    • 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.

  3. Sign off on the quarterly paydown
    Collects list Collects paragraph Collects signature