How-To2026-09-0310 min read

How to Track Technical Debt in Jira

Technical debt is invisible until it is not. Teams accumulate it through shortcuts, deferred refactoring, and evolving requirements, then experience it as slower delivery velocity, more bugs, and engineering frustration. The reason it festers is not that teams do not know about it but that they do not have a systematic way to track, prioritize, and schedule it alongside feature work. Without visibility, debt loses every prioritization battle to new features.

Jira is where most engineering teams already track their work, which makes it the right place to track technical debt. The challenge is structuring Jira so that debt items are visible to PMs and engineering leads without cluttering the sprint board. This guide sets up a dedicated tracking system that integrates with your existing workflow rather than creating a parallel one.

Step-by-step guide

01

Create a Technical Debt issue type

In your Jira project settings, create a custom issue type called 'Tech Debt.' Give it a distinct icon so it stands out visually on boards and in backlogs. This is better than using labels because issue types are filterable in JQL, visible on boards, and can have their own workflow. Map the new issue type to your existing workflow (To Do, In Progress, In Review, Done) so it follows the same sprint process as feature work.

  • Navigate to Project Settings > Issue Types and create 'Tech Debt' issue type
  • Assign a distinct icon (wrench or warning symbol)
  • Map it to your existing team workflow
02

Add custom fields for debt classification

Create three custom fields on the Tech Debt issue type. First, a Debt Category select field with options: Architecture, Code Quality, Testing, Dependencies, Documentation, and Performance. Second, a Severity select field: Critical (blocking feature work), High (causing bugs or slowdowns), Medium (increasing maintenance cost), Low (cosmetic or minor). Third, an Estimated Interest number field representing the hours lost per month if the debt is not addressed. This field makes the cost of inaction concrete.

  • Add Debt Category field with 6 predefined options
  • Add Severity field: Critical, High, Medium, Low
  • Add Estimated Interest field (hours lost per month) as a number
03

Set up a Tech Debt backlog board

Create a Jira board filtered to the Tech Debt issue type using a JQL filter: project = YOUR_PROJECT AND issuetype = 'Tech Debt' ORDER BY priority DESC, created DESC. This gives engineering leads and PMs a dedicated view of all outstanding debt without mixing it with the feature backlog. Use board columns matching your severity levels so the most impactful items are visually prominent.

  • Create a board with a JQL filter for Tech Debt issue type only
  • Configure columns by severity or by workflow status
  • Pin the board link in your engineering Slack channel for visibility
04

Establish a debt capture workflow

Make it easy for engineers to log debt when they encounter it. Create a Jira issue template for Tech Debt that pre-fills the issue type and prompts for: what the debt is, where it lives in the codebase (file paths or module names), why it was incurred (original context), what the impact is (bugs, slowdowns, or blocked work), and the estimated effort to fix it. Encourage engineers to create debt items during code review when they notice shortcuts. The friction to log debt should be as low as possible.

  • Create an issue template with structured fields for context and impact
  • Add a Slack shortcut or bookmark for quick debt logging
  • Encourage debt creation during code review as standard practice
05

Integrate debt into sprint planning

Allocate a fixed percentage of each sprint to tech debt work. A common ratio is 80/20 (80% features, 20% debt) or a fixed number of story points per sprint. During sprint planning, pull from the Tech Debt board based on severity and estimated interest. The PM and tech lead should jointly prioritize debt items using the estimated interest field: debt that costs the team 10 hours per month should be fixed before debt that costs 1 hour per month, regardless of which is easier.

  • Establish a fixed sprint allocation for debt work (e.g., 20% of capacity)
  • Prioritize by estimated monthly interest cost during planning
  • Track debt velocity separately from feature velocity for trending
06

Build a debt dashboard for leadership visibility

Create a Jira dashboard with gadgets showing: total open debt items by severity (pie chart), debt items created versus resolved per sprint (trend line), total estimated monthly interest cost (number), and the top 10 highest-interest items. Share this dashboard with engineering leadership and product leadership. When someone asks why velocity is decreasing, you can point to the rising interest cost on the dashboard instead of having an abstract conversation about code quality.

Common mistakes

Treating tech debt as a single backlog item

Creating one Jira epic called 'Address Technical Debt' is not tracking. Each piece of debt needs its own issue with its own classification, severity, and estimated interest. You cannot prioritize a single bucket; you prioritize individual items. Break debt down to the level where each item can be completed in 1-3 days.

Letting debt items sit in the backlog indefinitely

Debt items that are logged but never scheduled send the message that logging is pointless. If you establish a capture workflow but never allocate sprint capacity to fix debt, engineers will stop logging it. The 80/20 sprint allocation must be a genuine commitment, not an aspiration.

Only tracking debt that engineers report

Some of the most impactful debt is visible in metrics, not code reviews. Increasing build times, growing flaky test counts, and rising error rates are all debt indicators. Set up automated Jira ticket creation from your CI/CD and monitoring tools for metric-based debt detection.

Not linking debt to feature work it blocks

A debt item without context on what it enables or unblocks is hard to prioritize. Use Jira's issue links to connect debt items to the feature epics they slow down. When a feature takes 3x longer because of underlying debt, the link makes the causal relationship visible.

Tips

Use the Estimated Interest field in your sprint review to show stakeholders the monthly cost savings achieved by fixing debt items that sprint

Create a quarterly 'Debt Sprint' where the team spends one full sprint focused entirely on high-severity debt items — this builds engineering morale and creates visible momentum

Add a Jira automation rule that escalates debt items from Medium to High severity if they have been open for more than 90 days without activity

Track the ratio of debt items created to resolved over time — a growing gap indicates that your allocation percentage needs to increase

How Vantage helps

Vantage's ticket generation is dependency-aware, so when it identifies that a new feature requires refactoring an existing module, it creates the debt cleanup ticket as a dependency of the feature ticket. This makes technical debt visible in the planning phase rather than the implementation phase, and ensures debt work is scheduled when it is actually needed rather than deferred indefinitely.

Frequently asked questions

Spend less time on setup, more on decisions

Vantage connects your tools and generates specs grounded in real data. Free to start.

Free to start. No credit card required.

Related reading