# Technical debt triage checklist: what to fix now, schedule, or accept

URL: https://pixelactstudio.com/resources/technical-debt-triage-checklist

> A technical debt triage checklist: 42 checks that score debt by security, data, revenue, and speed risk, then sort each item into fix now, schedule, or accept.

A technical debt triage checklist sorts the known shortcuts in a codebase by the harm they can do, so the dangerous ones get fixed first. This checklist scores each item for security, data, revenue, and delivery speed risk, prices the cost of waiting, and ends every item in one of three decisions: fix now, schedule, or accept.

The checklist is for founders, CTOs, and engineering leads at seed and Series A startups with a backlog of “tech debt” tickets nobody can rank. Use it when a new CTO inherits a codebase, when simple changes start taking days, before a fundraise or due diligence, or before committing budget to a rebuild. Taking on debt to launch was a reasonable trade, and this list shows which part to pay back first.

## How do you use the technical debt triage checklist?

- Work through it with someone who can read the code and open the hosting and database dashboards.
- Answer each check yes or no. “I think so” counts as no, and so does a check nobody on the team can answer.
- Write every no into your debt register as one item, tagged with the risk it carries: security, data, revenue, or speed. A no in the first section or the last two is a gap in the triage process itself, and it goes on the list too.
- Give each item two rough numbers, its cost of delay and its fix size in days, then sort it with the guide at the end of this page.

## How do you start a technical debt assessment?

- [ ] Is every known piece of debt written in one register, such as a labeled issue list, rather than spread across chat threads, code comments, and memory? Debt nobody wrote down cannot be ranked, so the loudest complaint wins the next sprint. Searching the code for `TODO`, `FIXME`, and `HACK`, and the issue tracker for words like “temporary”, finds items the team forgot.
- [ ] Does each item name the file, service, or setting involved and the symptom it causes, in a sentence a non-engineer can follow? An item that says “auth is messy” cannot be sized or closed. “Admin pages check the role only in the browser” can be scored, assigned, and verified once it is fixed.
- [ ] Does each item have one named owner who can explain it and size the fix? Unowned items sit in the backlog until they cause an incident. The owner does not have to do the fix, but they keep the description and the estimate current.
- [ ] Do you know which 20 files changed most in the last six months? Debt in code that changes every week taxes every feature, while debt in a file nobody touches costs almost nothing. `git log --since='6 months ago' --format= --name-only | grep . | sort | uniq -c | sort -rn | head -20` lists the most-changed files. Skip lockfiles and generated code in the result.
- [ ] Is each recent outage, incident, or customer-reported bug linked to the debt item behind it, where there is one? An item tied to three incidents this quarter outranks a dozen that have caused none. Incident links turn opinions about code quality into evidence the whole team can see.
- [ ] Have you asked support, sales, and ops which workarounds they run every week, such as manual data fixes or restarted jobs? Some of the costliest debt never shows up in a code review, because people outside engineering absorb it. A support lead who edits rows by hand every Monday is paying interest on a missing admin action or a broken sync.

## Could the debt expose data or accounts?

- [ ] Does `npm audit --omit=dev`, or your language's equivalent, report no high or critical vulnerabilities in production dependencies? Published vulnerabilities are the easiest holes to find, because the advisory explains them. If a finding appears in [CISA's Known Exploited Vulnerabilities catalog](https://www.cisa.gov/known-exploited-vulnerabilities-catalog), which lists flaws exploited in the wild, it goes straight to fix now.
- [ ] Does production run on a supported runtime and framework version, such as a Node.js LTS release, rather than one past end of life? The [Node.js end-of-life page](https://nodejs.org/en/about/eol) states that a version past end of life no longer receives updates, including security patches. Every advisory published after that date stays open on your servers.
- [ ] Are authorization checks done in one shared place on the server, so no route can read or write data without them? Checks copied into each route drift apart, and the route that was missed returns another customer's records to anyone who changes an ID. Broken access control ranks first in the [OWASP Top 10:2025](https://top10.owasp.org/2025/A01_2025-Broken_Access_Control), so a known gap here is fix now even when the fix touches many files.
- [ ] Is each customer's data separated by an organization or tenant ID that the API or row-level security enforces, not only by filters in the UI? A boundary that lives only in the interface fails the first time someone calls the API directly. Adding one later touches most queries and tables, and the cost grows with every table built without it.
- [ ] Has every secret that ever appeared in git history been rotated at the provider? Deleting a key from the code leaves it in history, where anyone with a clone can recover it with `git log -p`. Rotation usually takes minutes and the exposure lasts until you do it, so this is always fix now.
- [ ] Have you removed everyone who left, including former contractors, from GitHub, hosting, the database, and the payment provider? Admin access held by people who no longer work with you is security debt that no code scan finds. It also blocks a clean answer when an enterprise security questionnaire asks who can reach production data.

## Could the debt lose or corrupt data?

- [ ] Have you restored a production backup into a separate database in the last 90 days, and timed it? Until a restore works once, you do not know whether backups are usable or how long recovery takes. An untested backup is fix-now debt, because the loss it risks cannot be undone.
- [ ] Is every schema change stored as a migration in the repository and applied by CI or the deploy, never by hand? Changes clicked into a database console leave production with a schema nobody can rebuild from the repository, and the next generated migration can fail against it. In Postgres, diffing `pg_dump --schema-only` output from production against a fresh database built from migrations shows the drift.
- [ ] Do unique, not-null, and foreign key constraints in the database enforce the rules the code assumes? Code that checks for a duplicate before inserting still lets two simultaneous requests create two accounts or two charges. Without constraints, bad rows pile up quietly, and every month adds more to clean before the next migration.
- [ ] Do jobs that move data, such as syncs, imports, and webhook handlers, record failures somewhere that alerts a person? A sync that fails silently can leave the CRM, the billing system, and your database disagreeing for weeks. The longer it runs, the more records someone has to reconcile by hand.
- [ ] Can you list where personal data is stored, including logs, analytics, and backups, and delete one customer's data on request? Under GDPR and UK GDPR, people can in many cases ask for their personal data to be erased, and enterprise questionnaires ask how you do it. Personal data copied into logs and third-party tools is debt that grows with every new customer.
- [ ] Is money stored as integer minor units, such as cents, or a decimal type, never as a floating-point number? In JavaScript, `0.1 + 0.2` returns `0.30000000000000004`, and rounding errors on invoices or payouts are hard to correct after customers have paid. The fix gets more expensive with every row and report that depends on the column.

## Is the debt costing revenue or customers?

- [ ] Have you marked which debt items sit on the paths that make money: signup, onboarding, the action customers pay for, checkout, and billing? The same shortcut costs different amounts in different places. A slow query in an internal report annoys one person, while the same query on checkout loses orders.
- [ ] Would a named person get an alert within minutes if signup, checkout, or billing started failing? Without an alert, a broken money path shows up as a customer email, often days later. An error tracker such as Sentry with alerts on those routes catches crashes, and an alert when completed signups or payments fall below their usual hourly count catches failures that throw no error.
- [ ] Do end-to-end tests cover those money paths and run in CI before every merge? Untested money paths make every nearby fix a gamble, so the team avoids the code and the debt stays. Five to ten Playwright tests there make later fixes safer to ship.
- [ ] Have you asked sales which deals stalled or were lost on a technical gap, such as no single sign-on, no audit log, or no data export? Debt that blocks a sale has a cost of delay you can name: the deal and its renewal. Put each gap on the register with the deals attached, so it competes on evidence rather than on who asks loudest.
- [ ] Have you tagged support tickets by product area for at least a month to see whether bugs cluster? A module that produces a bug report every week costs support time and customer trust, whatever its code looks like. Clusters show which debt to read first.
- [ ] Have you measured response times on your slowest customer-facing pages and endpoints at the 95th percentile, not the average? Averages hide the slow requests your largest customers feel, because they have the most data. The [performance and scalability checklist](https://pixelactstudio.com/resources/performance-scalability-checklist) covers how to find the queries behind them.

## How much is the debt slowing delivery?

- [ ] Can a new engineer clone the repository and run the app locally within a day, from written steps? Setup that lives in one person's head costs days for every hire and contractor, and it stops anyone else from fixing urgent debt quickly. A README with exact commands and a seed script is often a one-day fix.
- [ ] Does CI finish tests, type checks, and linting on a typical pull request in under 15 minutes, without reruns? Slow or flaky pipelines push engineers to batch changes into large pull requests, which are harder to review and riskier to release. Count how often a rerun turns a red build green, since each one points to a flaky test or step to fix or delete.
- [ ] Can you deploy on a normal workday and roll back in minutes, with a rollback you have tried at least once? When releases feel risky, teams ship less often and bundle more changes together, so each failure is bigger and harder to trace. Our guide to [safe releases and rollbacks](https://pixelactstudio.com/blog/safe-releases-and-rollbacks) sets out the minimum setup for a small team.
- [ ] Does each business rule, such as pricing, permissions, or plan limits, live in one place in the code? Pricing logic copied into four screens means every change takes four edits, and one usually gets missed. Duplicated rules are typical schedule items, best fixed the next time the team works in that area.
- [ ] Can the team name the modules where a small change regularly takes days instead of hours, with recent examples? This is the interest payment on speed debt, and engineers usually know where it sits. Two or three examples per module, with the real time taken, make the cost of delay evidence rather than a feeling.
- [ ] Are major dependencies at most one major version behind, with Renovate or Dependabot opening update pull requests? Upgrading one major version at a time is routine, while jumping three at once can take weeks. Security fixes often ship only on newer versions, so a large upgrade gap turns speed debt into security debt.

## How do you prioritize technical debt by cost of delay?

- [ ] Have you estimated, for each item, what waiting one more quarter would cost in engineering hours, incidents, or deals? Outside the fix-now list, cost of delay is the deciding number. Count the steady cost, such as 20 engineering hours a month lost in a slow module, and the risk cost, such as an outage that grows more likely every quarter. Rough written estimates are enough to compare items.
- [ ] Does each item have a rough fix size in days from someone who has read the code? Dividing cost of delay by fix size ranks items fairly, a rule product teams call weighted shortest job first: a two-day fix that saves a day a week beats a six-week refactor with the same saving. Sizes guessed from outside the code miss the hidden work, such as data migrations and the tests that must come first.
- [ ] Have you checked whether each item gets more expensive over time, for example with every new customer, table, or feature built on top? Some debt compounds. A missing tenant ID costs one migration today, and later a migration plus a backfill for every table added since, so compounding items move up the list even when their cost today is small.
- [ ] Is every item marked fix now, schedule, or accept, with nothing left as “someday”? Undecided items get reread at every planning meeting and decided never. Three explicit outcomes force a choice and keep the register short enough to use.
- [ ] Does every scheduled item have an owner, a target month, and a link to the feature work it will ride along with? Debt paid down inside feature work in the same area costs less, because the code is already open and being tested. A scheduled item with no date is an accepted item nobody admitted to.
- [ ] Does every accepted item record why it is acceptable and a date to review it? Accepting debt is a valid decision when the code is stable, rarely changed, or due to be retired. The [GDS Way guidance on technical debt](https://gds-way.digital.cabinet-office.gov.uk/standards/technical-debt.html) for UK government teams notes that risk does not map directly to priority, for example when a risky component will go away anyway, and asks teams to review every rating periodically.

## How do you keep technical debt from growing back?

- [ ] Does every pull request that takes a shortcut also add a register item, linked from the review? Deliberate debt is a sensible trade before a launch or a demo, as long as it is recorded when it is taken. A “debt introduced” field in the pull request template costs nothing and keeps the register current.
- [ ] Do required CI checks block merges on failing tests, type errors, lint errors, and new high-severity dependency advisories? Rules that only run on laptops stop being followed in the first busy week. A required check holds every change to the same bar, whoever or whatever wrote it.
- [ ] Does a person who knows the system review every change to sign-in, payments, personal data, and the schema, including changes written with AI coding tools? AI coding tools make large changes cheap to produce, and review is where new debt is either caught or merged. Our [AI code review workflow](https://pixelactstudio.com/blog/ai-code-review-workflow) shows how to split the work between automated review and the engineer who approves.
- [ ] Are the reasons behind major technical choices written down, for example as architecture decision records? Without the reasoning, engineers either avoid code they do not understand or undo a choice that had a good reason. Our guide to [architecture decision records](https://pixelactstudio.com/blog/architecture-decision-records) includes a short template.
- [ ] Is a fixed share of each cycle reserved for scheduled debt, and checked against the register every month? Without reserved time, scheduled items slip behind every feature request until they become incidents. A monthly look also catches items whose cost of delay has changed, such as a module that now changes every week.
- [ ] Do you rerun this triage each quarter, and before a fundraise, a key hire, or a rebuild decision? Priorities shift as the product does, and a module nobody touched last quarter may sit on this quarter's roadmap. Once the register exists, each pass mostly updates scores rather than starting from scratch.

## Which tech debt should you fix first?

Fix technical debt first when it can expose data, lose data, or stop customers from paying, whatever the fix costs. Rank everything else by cost of delay divided by fix size.

### Which failures are urgent?

- A production dependency with a vulnerability exploited in the wild, or a runtime past end of life.
- A known gap in authorization or tenant separation.
- A secret in git history that has not been rotated.
- Backups never restored, or a schema that exists only in production.
- A money path with no alert, so a failure reaches you through a customer.

These go to fix now, ahead of any refactor. Most take days, though closing a tenant separation gap can take longer because it touches most queries.

### What can you schedule or accept?

Schedule revenue and speed items whose cost grows each month, with an owner and a date, and pay them down alongside feature work in the same area. Accept items in stable or soon-retired code, in writing, with a review date.

### When does an outside review make sense?

Get an outside review when the fix-now list is longer than your team can clear in two weeks, when nobody can answer a whole section, when the team is split on a rebuild, or when a fundraise depends on the answers. A [Pixelact software audit](https://pixelactstudio.com/services/software-audits) is a fixed package from $2,500: about 3 to 5 days of review, a written report that ranks risks and fixes, a build path with rough costs, and a walkthrough call. If releases already break every week, [software rescue](https://pixelactstudio.com/services/software-rescue) starts with a rescue audit at the same price, which ends in a fix-or-rebuild call.

To see the format first, [request an audit](https://pixelactstudio.com/request-an-audit) and ask for the sample report we made from one of our own products.

## Frequently asked questions

### How much time should a startup spend on technical debt?

There is no correct percentage. A fixed share of each cycle, such as one day in ten, suits scheduled debt, but fix-now items jump the queue whatever the budget says, and accepted items get no time at all. Size the share so each scheduled item can meet its date. If the team has no room, an [engineering retainer](https://pixelactstudio.com/services/engineering-retainers) adds fixed monthly capacity, offered once Pixelact has worked in the code through a build or a stabilization sprint.

### What is the difference between technical debt and a bug?

A bug is behavior that is wrong today, such as an invoice that adds tax twice. Technical debt is a shortcut in how the code is built that makes future changes slower or riskier, such as tax logic copied into four places. Debt often causes bugs, so a bug that keeps returning in the same module is a strong sign the debt behind it belongs on the fix-now or scheduled list.

### Should we pause feature work to pay down technical debt?

Rarely. A feature freeze stalls the roadmap and often ends before the debt does. Clear the fix-now items, which usually take days, then pay scheduled debt down when the team next changes that area, and plan larger items as named tasks with an owner and a date. Pausing features in one area makes sense only when every change there breaks something else.

### How do we explain technical debt to investors or a board?

Show the register, not the code. List each fix-now item with its risk in plain words and the date it will close, then give the number of scheduled items with their plan and the accepted items with their reasons. “Backups have never been restored” is easier to weigh than a code quality score. Our guide to [what a software audit covers](https://pixelactstudio.com/blog/what-a-software-audit-covers) shows a report format a non-engineer can read.

### Does a lot of technical debt mean we need to rebuild?

Usually not. Missing tests, slow queries, outdated dependencies, and duplicated logic can all be paid down in place. Replacing one part is worth weighing when its data model or security model blocks what the product must do next, and fixing it in place would touch most of its files anyway. Our guide to [deciding whether to rebuild or refactor](https://pixelactstudio.com/blog/rescue-or-rebuild) explains how to judge it part by part.