Analyze and Remediate Technical Debt

This skill acts as a technical debt expert, identifying, quantifying, and prioritizing technical debt across a codebase and creating actionable remediation plans focused on measurable improvements with clear ROI.

It runs a technical debt inventory across five categories: code debt (duplicated code, high cyclomatic complexity above 10, deeply nested conditionals, long methods over 50 lines, God classes over 500 lines/20 methods, circular dependencies, feature envy); architecture debt (missing or leaky abstractions, violated architectural boundaries, monolithic components, outdated frameworks, deprecated API usage); testing debt (coverage gaps, brittle or flaky tests, slow suites); documentation debt (missing API docs, undocumented complex logic, no architecture diagrams); and infrastructure debt (manual deployment steps, no rollback procedures, missing monitoring).

It calculates the real cost of each debt item with concrete examples - e.g. duplicate validation logic across 5 files costing an estimated $36,000/year in fix and change time, or missing payment-flow integration tests costing an estimated $48,600/year in bug investigation and fixes - and assigns risk levels (Critical/High/Medium/Low). It builds a debt metrics dashboard (cyclomatic complexity, duplication percentage, test coverage by type, dependency health) and tracks quarter-over-quarter debt-score trends with a growth-rate projection.

Its prioritized remediation plan is ROI-ordered: quick wins (1-2 weeks, e.g. extracting duplicate validation logic for an estimated 250% first-month ROI), medium-term improvements (1-3 months, e.g. splitting a God class into focused services, or a major framework upgrade), and long-term initiatives (2-4 quarters, e.g. Domain-Driven Design adoption or a comprehensive test suite). Its implementation strategy favors incremental refactoring via a facade pattern with feature-flagged gradual migration from legacy to new code, plus dedicated team time allocation (e.g. 20% sprint capacity) and sprint-by-sprint goals.

Its prevention strategy defines automated quality gates (pre-commit complexity/duplication/coverage checks, CI dependency audits and performance regression checks, code review requirements) and a debt budget (e.g. max 2% monthly debt increase, 5% mandatory quarterly reduction, tracked via SonarQube/Dependabot/Codecov). It produces stakeholder reports (executive summary with debt score, velocity loss, key risks, proposed actions) and developer documentation (a refactoring guide and code standards), tracked against monthly and quarterly success metrics (debt score reduction, bug rate, deployment frequency, lead time, test coverage).

# Phase 1: Add facade over legacy code
class PaymentFacade:
    def __init__(self):
        self.legacy_processor = LegacyPaymentProcessor()

    def process_payment(self, order):
        # New clean interface
        return self.legacy_processor.doPayment(order.to_legacy())

# Phase 3: Gradual migration
class PaymentFacade:
    def __init__(self):
        self.new_service = PaymentService()
        self.legacy = LegacyPaymentProcessor()

    def process_payment(self, order):
        if feature_flag("use_new_payment"):
            return self.new_service.process_payment(order)
        return self.legacy.doPayment(order.to_legacy())

Use this skill for technical debt analysis and remediation tasks - inventorying debt, calculating its cost and risk, building a prioritized ROI-based remediation roadmap, and establishing prevention gates.

Not for tasks unrelated to technical debt analysis and remediation, or where a different domain or tool is needed.

Inputs: a codebase to analyze for technical debt across code, architecture, testing, documentation, and infrastructure.

Outputs: a categorized debt inventory with metrics, an impact analysis with cost calculations and risk levels, a quarter-by-quarter prioritized roadmap, immediate quick wins, a step-by-step implementation guide, a prevention plan with automated quality gates, and ROI projections.

SonarQube, Dependabot, Codecov (referenced for tracking complexity, dependencies, and coverage); CI pipelines for automated quality gates.

Engineering teams and tech leads who need to quantify technical debt's real cost, build an ROI-justified remediation roadmap, and put prevention gates in place to stop new debt from accumulating.