How to Track Tech-Debt Decisions

What Technical Debt Actually Is

The term "technical debt" was coined by Ward Cunningham in 1992 as a deliberate analogy to financial debt: the cost of taking a shortcut today is that you pay interest in the form of slower future development until you repay the principal by doing the work correctly.

Cunningham's original definition was narrow and specific: technical debt is the gap between the understanding you have when you write code and the understanding you wish you'd had. His point was that software written with less understanding than ideal requires rework as understanding improves — and that the rework is the debt repayment.

In practice, technical debt has come to mean something broader: any code, architecture, or infrastructure decision where a faster or simpler approach was chosen, creating a future cost. This broader definition covers:

• Deliberate shortcuts taken to hit a deadline, with the intention to clean up later
• Code written when the team had less domain knowledge, now known to be wrong
• Architecture that made sense at one scale but doesn't at a larger one
• Dependencies that were expedient when chosen but have become liabilities
• Accumulated small compromises that each seem acceptable individually but compound

The distinction that matters for tracking is intentional vs. unintentional debt. Intentional debt is a decision made with awareness of the trade-off: "we're using a polling approach for real-time updates now because a proper event streaming architecture would take three additional weeks; we accept that we'll need to rework this when we scale past 10,000 concurrent users." Unintentional debt is discovered later: "why is this authentication middleware doing a synchronous database call on every request? Who wrote this?"

Intentional debt is manageable. It was a trade-off with a known cost, and the team can decide when to repay it. Unintentional debt is risk: unknown, invisible until it manifests as a production problem or a development bottleneck.

Tracking technical debt means converting it from unintentional to intentional — making the trade-offs explicit, recording the context, and building a visible backlog that can be prioritized alongside feature work.

---

Why Most Teams Don't Track Tech Debt

Most engineering teams have untracked technical debt by default. The reasons are structural:

Debt is created under deadline pressure. The conditions that create tech debt (a deadline, a launch, a customer commitment) are exactly the conditions under which documentation is skipped. Writing a tech debt entry feels like overhead when the team is already behind.

The team that created the debt isn't always the team that repays it. If the team that made the shortcut knows they'll never fix it, they have less incentive to document it. If they leave, the debt is invisible to the new engineers.

There's no natural trigger for debt discovery. New features have tickets; bugs have issue reports. Technical debt is discovered asymmetrically: it often surfaces as friction (slower development, more incidents, harder onboarding) rather than as a discrete event.

Tracking debt feels like admitting failure. There is sometimes a cultural aversion to making technical debt visible — it can feel like exposing poor past decisions rather than honest trade-offs.

The counter-argument: invisible debt compounds faster than visible debt. Teams that don't track technical debt don't have less of it — they have the same debt plus the additional cost of not knowing where it is.

---

The Tech Debt Register

The tracking artifact that works for most teams is a tech debt register: a structured list of known technical debt items, each with enough context to make it actionable.

A tech debt register entry has five fields:

1. ID and title: A unique identifier and a short, specific name. "TD-047: Polling-based presence system" is more useful than "real-time update debt." The title should name the specific system or component with the debt, not the abstract category of debt.

2. Description: What the debt is, specifically. Not "bad code" or "needs refactoring" — what specific decision was made, what the ideal implementation would look like, and what the gap is. "The presence system uses 5-second HTTP polling from each client. The correct implementation for our scale is WebSocket-based server-sent events. We chose polling in Q3 2025 because the WebSocket infrastructure didn't exist yet."

3. Reason / context: Why was this decision made? What were the constraints? The context field is what makes a debt entry useful six months later, when the people who made the decision may have left. "WebSocket infrastructure was not yet available. Polling was the fastest path to the feature for the Q4 launch. Decision made 2025-09-15 by @tech-lead."

4. Impact: What cost does this debt impose? This is the "interest" on the financial debt analogy. Measurable impacts are more useful than vague ones. "Polling generates 340k HTTP requests/hour at 1,000 concurrent users. At our current scale (3,000 concurrent), we're at 1M+ requests/hour — contributing an estimated 18% to our API gateway costs. Development impact: any change to presence behavior requires testing across 50+ polling scenarios."

5. Remediation: What would it take to repay this debt? An estimate of the effort (even a rough one), a description of the approach, and any dependencies or blockers. "Migrate to WebSocket-based server-sent events. Estimated 3-4 sprints. Blocked on completing the event streaming infrastructure work (ETA: Q2 2026). Owner: @platform-team."

A debt register entry doesn't need to be long — 200-300 words per entry is sufficient. What it needs to be is specific and honest.

---

Debt Severity Classification

Not all technical debt has the same urgency. A classification system that's simple enough to maintain:

Critical (repay within 2 sprints): Debt that is actively blocking current work, causing production incidents, or creating a security or compliance risk. A critical debt item should go directly into the next sprint planning.

High (scheduled in the next quarter): Debt that is slowing development measurably — engineers are working around it, or it's causing predictable problems every few sprints. High-severity debt should appear in quarterly planning and receive dedicated sprint time.

Medium (tracked, reviewed quarterly): Debt that is real but not urgent — it creates friction but doesn't block work. Reviewed in quarterly planning; occasionally picked up during lower-priority sprints.

Low (tracked, no action date): Debt that is known and documented but not currently worth addressing. The system works, and the improvement would be a nice-to-have rather than a needed fix.

Severity should be reassessed quarterly. Debt that starts as Low can become Critical as the system grows or as dependent work accumulates around it.

---

When to Create a Debt Entry

The trigger model for debt entries:

At the time of the decision: When the team makes a deliberate shortcut — "we'll do this the simple way now and fix it later" — a debt entry should be created at the same time as the decision. This is the highest-quality entry because the context is fully loaded.

When debt is discovered in code review: When a reviewer identifies existing code that represents a known-but-undocumented shortcut. The reviewer creates the debt entry rather than adding a code comment. Code comments about technical debt ("TODO: fix this") are invisible at the project level.

After an incident: When a postmortem identifies a structural debt (the incident happened because of a known architectural limitation), creating a debt entry is a postmortem action item.

During onboarding: When a new engineer encounters something and asks "why is it done this way?" and the answer is "because of constraints that no longer exist" — that's undocumented debt. The conversation should produce an entry.

---

Integrating Debt into Sprint Planning

A tech debt register is only useful if it influences the work the team does. Integration into sprint planning:

The quarterly review: Once per quarter, the tech debt register is reviewed in a team session. Each entry is re-evaluated: has its severity changed? Has the context changed (dependencies resolved, new constraints appeared)? Is anything that was Medium now High because of adjacent work?

The sprint allocation: Reserve a percentage of sprint capacity — typically 15-20% — for technical debt repayment. This is not wasted capacity; it's the interest payment that prevents the debt from compounding. Teams that never allocate sprint time to debt repayment see their delivery velocity decline over time as the debt makes all feature work slower.

The debt-as-prerequisite pattern: When a new feature requires working in an area with known High or Critical debt, address the debt first. This is the "make it possible, then make it work, then make it right" principle: don't layer new complexity on top of existing structural problems.

---

Tools

A tech debt register doesn't need a dedicated tool. Options:

A section in the team wiki (Notion, Confluence): A structured table with the five fields above, linked from the team's engineering docs. Best for teams that want the register co-located with other team documentation.

Linear or Jira debt backlog: A label or project for technical debt items. Each debt item is a ticket. The advantage: debt items can be scheduled into sprints alongside feature work. The disadvantage: ticket-based systems encourage thin descriptions; debt context is often lost.

A TECH_DEBT.md file in the repository: Version-controlled, visible to all engineers, searchable via code search. Works well for smaller teams. The discipline required: keep it in the repository root (or a docs/ folder) and update it in the PR that creates the debt.

Shortcut or GitHub Issues with a "tech-debt" label: Similar to Linear/Jira — the labeling system is the register. Works well for teams already using these tools for issue tracking.

The tool is less important than the discipline: debt entries created at decision time, reviewed quarterly, and allocated sprint time for repayment.

---

Worked Example: A Startup's Debt Register

Setup: A 15-engineer startup has been building for three years. They've never tracked technical debt formally. The CTO notices that sprint velocity has dropped 30% over the past six months without a clear cause. She suspects accumulated debt but can't quantify it.

What they do:

Over two weeks, the team conducts a "debt discovery" sprint. Every engineer documents the technical debt they're aware of in the systems they own. They produce 34 entries.

Classification: 3 Critical, 9 High, 14 Medium, 8 Low.

The three Critical items: the authentication service's session management code (a synchronous database call in the hot path, causing latency spikes under load); the payment processing integration (using a deprecated API version that will be discontinued in Q1); and the deployment pipeline (no staging environment, all testing happens in production).

These three items are addressed in the next two sprints. Sprint velocity increases. The CTO's hypothesis was correct — the three Critical items were the primary source of the velocity degradation.

The 9 High items are scheduled across Q1. The register is reviewed quarterly.

---

Key Takeaways

1. Intentional debt is manageable; unintentional debt is risk: tracking technical debt converts it from invisible risk into explicit trade-offs that can be prioritized and repaid.
2. The five-field register entry (ID, description, reason/context, impact, remediation) captures enough to act on the debt months after it was created: context is the field that becomes most valuable over time.
3. Create debt entries at decision time, not discovery time: the context is richest when the shortcut is being made; debt entries created retrospectively are less accurate.
4. Severity classification enables prioritization: Critical and High debt belongs in sprint planning; Medium and Low debt is tracked and reviewed quarterly.
5. Allocate 15-20% of sprint capacity to debt repayment: teams that never allocate sprint time to debt see velocity decline; the allocation is interest payment, not waste.

---

Conclusion

Technical debt is inevitable in any software system that evolves under real-world constraints. The question is not whether to incur it — it will be incurred — but whether it's tracked, classified, and systematically repaid, or allowed to accumulate invisibly until it manifests as degraded velocity, increased incidents, and engineering frustration. A tech debt register with entries created at decision time, reviewed quarterly, and connected to sprint planning is the practice that converts technical debt from a liability into a managed trade-off.

Try WebSnips free — save technical debt references, architecture decision notes, and engineering best practices with your own context annotations, tag by system and severity, and build the organized developer knowledge base that keeps your technical debt visible and your engineering decisions intentional.