Technical Debt

The TODO/FIXME/HACK convention with mandatory expiration dates, debt classification, and hotspot analysis.

Technical debt is inevitable in a fast-moving project. These conventions ensure debt is tracked, categorized, and surfaced before it becomes dangerous. The goal is not zero debt -- it is zero invisible debt.

TODO/FIXME/HACK Convention

Every TODO, FIXME, or HACK comment must include either an expiration date or a Linear ticket number. Bare comments like // TODO: fix this are ESLint errors.

Format

// TODO [2026-06-01]: Replace with proper caching after Redis upgrade
// TODO [TRO-99]: Refactor after migration is complete
// FIXME [2026-05-15]: This workaround breaks when org has > 100 members
// HACK [2026-04-30]: Temporary bypass until auth middleware is updated

When to use each

TODO -- planned improvement, not urgent. Use a date 2-4 weeks out or a ticket.
FIXME -- known bug or incorrect behavior. Use a near-term date or a ticket.
HACK -- intentional shortcut that must be replaced. Always use a short date (1-2 weeks).

What happens when they expire

When the date passes, ESLint promotes the comment to an error. CI will fail until the TODO is either addressed or the date is extended. Extending the date is acceptable but requires updating the comment with context explaining why.

This is enforced by unicorn/expiring-todo-comments. See Quality Gates -- ESLint Configuration for the rule configuration.

Debt Classification

Based on Martin Fowler's Technical Debt Quadrant. Use this to prioritize what to fix first.

Reckless + Deliberate

"We know this is wrong but we are shipping anyway."

Example: Skipping auth checks to meet a deadline
Action: Track in Linear immediately. Fix before next release.
/arch-review severity: HIGH or CRITICAL

Prudent + Deliberate

"We know this is a shortcut and we will fix it later."

Example: Hardcoded config value instead of pulling from settings
Action: Add an expiring TODO with a date. Acceptable short-term.
/arch-review severity: MEDIUM

Prudent + Inadvertent

"Now that we have built it, we see how it should have been done."

Example: Realizing two modules should share a common abstraction
Action: Refactor when the area is next touched. No TODO needed -- the improvement is obvious in context.
/arch-review severity: LOW

Reckless + Inadvertent

"AI generated this and nobody reviewed the design."

Example: Duplicated business logic across packages, over-complex function that works but is fragile
Action: Caught by /arch-review skill and lint tooling. Fix when flagged.
/arch-review severity: Varies (caught by complexity rules, duplication detection, coupling analysis)

Hotspot Analysis

Hotspots are files that are both frequently changed (high git churn) and complex (ESLint complexity violations). These are the most dangerous debt -- bugs are most likely to be introduced here.

Running the analysis

# Default: last 90 days, top 20 files
pnpm hotspots

# Custom: last 180 days, top 30 files
bash scripts/hotspot-analysis.sh 180 30

# JSON output (for CI artifacts or reporting)
bash scripts/hotspot-analysis.sh 90 20 json

Reading the output

Color	Meaning	Action
RED	High churn + complexity violations	Refactor priority -- these files are actively accumulating risk
YELLOW	High churn, no complexity issues yet	Monitor -- complexity may be creeping up
GREEN	Moderate churn, clean	Healthy -- no action needed

When to run

On demand when planning refactoring work
Monthly as part of the full /arch-review audit (TRO-97)
After a sprint with heavy changes to a single area

The Debt Lifecycle

Debt is created -- a shortcut is taken, tagged with TODO/FIXME/HACK and an expiration date
Debt is visible -- it shows as a lint warning in the editor, appears in /arch-review reports
Debt expires -- ESLint promotes the comment to an error, CI fails
Debt is resolved -- the code is fixed, the comment is removed; or the date is extended with updated context
Systemic debt is surfaced -- hotspot analysis identifies files where debt has accumulated into structural risk

Delivery -- Quality Gates -- ESLint unicorn/expiring-todo-comments enforcement
Delivery -- Architecture Enforcement -- Hotspot Analysis -- the tooling behind hotspot detection
Delivery -- Architecture Enforcement -- Review and Audits -- the /arch-review skill that scores debt