Tech Debt Remediation Agent

Your agent for analyzing, prioritizing, and planning the remediation of technical debt — producing actionable, concise remediation plans without modifying code directly.

When to Use This Agent

Choose Tech Debt Remediation Agent when:

• Assessing the current state of technical debt in a codebase
• Prioritizing debt items by business impact, risk, and remediation effort
• Creating structured remediation plans with clear milestones
• Evaluating whether to refactor, replace, or accept specific debt
• Preparing technical debt proposals for stakeholder buy-in

Consider alternatives when:

• You need to actually refactor code — use a refactoring agent
• You need automated code quality metrics — use SonarQube or CodeClimate
• You need architectural redesign — use a cloud architect agent

Quick Start

Copy
# .claude/agents/tech-debt-remediation.yml
name: Tech Debt Remediation Agent
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
description: Technical debt analysis agent that produces remediation plans — analysis only, no code modifications

Example invocation:

claude "Analyze the technical debt in our authentication module — identify legacy patterns, assess risk, and create a prioritized remediation plan with effort estimates"

Core Concepts

Technical Debt Classification

Category	Description	Examples
Design Debt	Architectural shortcuts	God objects, circular dependencies, missing abstractions
Code Debt	Implementation quality	Duplicated code, magic numbers, complex conditionals
Dependency Debt	Outdated or risky dependencies	Unmaintained libraries, version lag, license issues
Test Debt	Insufficient or brittle tests	Low coverage, flaky tests, missing integration tests
Documentation Debt	Missing or stale docs	Undocumented APIs, outdated READMEs, missing ADRs
Infrastructure Debt	Platform and tooling gaps	Manual deployments, missing monitoring, legacy CI

Remediation Plan Structure

Copy
# Tech Debt Remediation Plan: [Area]

## Executive Summary
- Debt severity: HIGH | MEDIUM | LOW
- Estimated effort: X person-weeks
- Business risk: What breaks if we don't fix this

## Findings
1. [Finding]: Description, impact, evidence
2. [Finding]: Description, impact, evidence

## Prioritized Actions
| Priority | Action | Effort | Impact | Dependencies |
|----------|--------|--------|--------|-------------|
| P0 | Critical fixes | S/M/L | High | None |
| P1 | Important improvements | S/M/L | Medium | P0 |
| P2 | Nice-to-have cleanups | S/M/L | Low | None |

## Implementation Roadmap
- Sprint 1: P0 items (critical safety)
- Sprint 2-3: P1 items (reliability)
- Ongoing: P2 items (quality of life)

Configuration

Parameter	Description	Default
scope	Analysis scope (module, service, repo, system)	repo
depth	Analysis depth (surface, moderate, thorough)	moderate
output_format	Report format (markdown, jira-tickets, spreadsheet)	markdown
effort_unit	Effort estimation unit (hours, days, story-points)	days
risk_framework	Risk assessment model (impact-effort, wsjf, rice)	impact-effort

Best Practices

1. Quantify debt in terms of business impact, not code quality. "This function is ugly" doesn't motivate remediation. "This module causes 30% of our production incidents and doubles onboarding time for new developers" gets budget and prioritization.

2. Classify debt as deliberate or accidental. Deliberate debt (shortcuts taken consciously for speed) has known scope and is easier to plan around. Accidental debt (accumulated unknowingly) requires discovery effort before planning. Both need different remediation strategies.

3. Create remediation tickets at a workable granularity. "Refactor the authentication system" is too vague to estimate or assign. "Extract token validation from UserController into dedicated TokenValidator service" is actionable, estimable, and completable in a single sprint.

4. Pair debt remediation with feature work. Pure refactoring sprints are hard to justify and create merge conflicts. Instead, attach remediation tasks to related feature work — when you're adding a new auth method, that's when you refactor the auth module.

5. Track debt reduction metrics over time. Measure before and after — test coverage, build times, incident frequency, deployment frequency, onboarding time. Without metrics, you can't demonstrate that remediation was worth the investment.

Common Issues

Stakeholders don't prioritize debt because the impact is invisible. Translate technical debt into metrics stakeholders care about: "This debt causes 2 extra hours per developer per week" or "This increases our incident rate by 40%." Attach dollar amounts when possible.

Remediation plan is too ambitious and never gets started. Large plans intimidate teams into inaction. Start with the smallest P0 item that delivers visible improvement. Quick wins build momentum and trust, making it easier to justify the next round of remediation.

Debt grows faster than the team remediates it. If every sprint adds more debt than it removes, you have a systemic problem. Address the root cause — tight deadlines, missing code review standards, lack of automated quality gates — before focusing on individual debt items.