Technical Debt in Startups: When to Fix It and When to Ship Anyway

The Debt That Will Kill You (Fix It Now)

Not all debt is equal. The debt that will actively compound and hurt you: missing database indexes on tables that are growing fast (every query gets slower as data grows), no error tracking or logging (you're debugging blind in production), authentication logic built manually instead of using a proven library (security holes compound silently), and hardcoded API keys in the codebase (a public GitHub commit exposes everything). Fix these before the next sprint, not 'someday.'

• Missing indexes on growing tables: fix immediately, cheap to add
• No error tracking (Sentry is free): fix before you have real users
• Hand-rolled auth: replace with Supabase Auth or Clerk — never worth maintaining
• Hardcoded secrets: move to environment variables, rotate the leaked keys

The Debt That Can Wait (But Has an Expiry)

These are the trade-offs that were probably fine to make at the start but will eventually bite: no test coverage (fine at 1,000 users, painful at 50,000), copy-pasted code in three places instead of a shared function (fine until you need to change behavior), no staging environment (fine for solo builds, breaks teams), and optimistic UI without proper error handling (users click a button and nothing happens — they don't know why). These aren't emergencies, but schedule them before your next major feature release.

The Debt That Was Actually the Right Call

Some things that look like technical debt are just features of an early-stage codebase: a monolith instead of microservices (monolith is faster to build and operate until you have 5+ engineers), a single Supabase project for everything (splitting into services is premature optimization before $1M ARR), manual deployment instead of CI/CD (fine when you're the only one pushing code). These aren't debt — they're appropriate architecture for your current scale. Engineering teams often push for 'enterprise patterns' prematurely. Resist it.

• Monolith: correct for any team smaller than 5 engineers
• No microservices: correct until a specific service needs independent scaling
• SQLite → Postgres migration: only needed when you need multi-server writes or RLS
• Manual deploys → CI/CD: required when more than one person pushes to main

The Refactor vs. Rewrite Decision

Rewrites are almost always the wrong answer. The classic Netscape mistake: declare the old codebase too messy to fix, spend 3 years rewriting, ship a product with all the same bugs plus new ones, lose market share. Refactoring — incrementally improving specific modules while keeping the system running — is almost always better. The exception: if the architecture prevents you from shipping a core business feature (e.g., no multi-tenancy and you're selling B2B), a targeted rewrite of that module may be justified. Not the whole codebase — one module.

How to Budget for Debt Paydown

The 20% rule: reserve one sprint day per week (or one sprint per month) for debt reduction and internal quality. This is the engineering team's rule, not an ad hoc conversation every six months. Track debt explicitly in your issue tracker — not in engineers' heads or in Slack messages. Before each sprint, pull one or two debt items into the sprint alongside feature work. Debt that isn't tracked doesn't get fixed.

• 20% of sprint capacity for debt: enforce it as a policy, not a feeling
• Debt backlog: tracked in Linear/Jira with severity labels
• Debt tickets written by engineers: they know where the bodies are buried
• Don't ship new features on a foundation you know is about to collapse