code-refactoring-tech-debt

Usage

Loaded automatically when its description matches the active task. The body below provides the working context.

Use this skill when

Conducting a technical debt analysis of a codebase
Planning a refactoring roadmap with ROI estimates
Identifying and classifying code smells
Creating prevention strategies to stop new debt accumulation
Communicating debt impact to stakeholders with measurable metrics

Do not use this skill when

The task is unrelated to technical debt or code quality
You need a specific refactoring pattern for a single function — use clean-code skill
You need performance optimization without quality concerns

Purpose

This skill provides a systematic framework for discovering all types of technical debt, calculating its real business cost, prioritizing remediation by ROI, and implementing prevention gates to stop new debt accumulation.

Capabilities

Technical Debt Inventory

Code Debt

Duplicated code: exact copy-paste duplicates, similar logic patterns, repeated business rules — quantify as lines duplicated and number of locations
Complex code: cyclomatic complexity above 10, nested conditionals deeper than 3 levels, methods longer than 50 lines, God classes exceeding 500 lines or 20 methods — quantify as complexity scores and hotspot locations
Poor structure: circular dependencies, inappropriate intimacy between classes (feature envy), shotgun surgery patterns where one change requires edits in many places — quantify as coupling metrics and change frequency

Architecture Debt

Design flaws: missing abstractions, leaky abstractions, violated architectural boundaries, monolithic components — quantify as component size and dependency violations
Technology debt: outdated frameworks, deprecated API usage, legacy patterns (callbacks instead of promises), unsupported dependencies — quantify as version lag and security vulnerability count

Testing Debt

Coverage gaps: untested code paths, missing edge cases, absent integration tests, no performance tests — quantify as coverage percentage and critical paths without tests
Test quality: brittle environment-dependent tests, slow test suites, flaky tests, undocumented tests — quantify as test runtime and failure rate

Documentation Debt

Missing documentation: undocumented public APIs, complex logic without explanation, absent architecture diagrams, no onboarding guide — quantify as undocumented public API count

Infrastructure Debt

Deployment issues: manual deployment steps, absent rollback procedures, missing monitoring, no performance baselines — quantify as deployment time and failure rate

Impact Assessment

Calculate the real cost of each debt item using this framework:

Identify time lost per occurrence (e.g., "must fix in 5 places = 2 hours per bug fix")
Multiply by frequency (monthly occurrences)
Multiply by cost per hour (developer rate)
This yields the monthly and annual carrying cost of the debt

Risk classification:

Critical: security vulnerabilities, data loss risk
High: performance degradation, frequent outages, developer blocking
Medium: slow feature delivery, developer frustration
Low: code style issues, minor inefficiencies

Debt Metrics

Key measurable KPIs to track:

Cyclomatic complexity average and files above threshold (target: <10)
Code duplication percentage (target: <5%)
Test coverage by tier: unit, integration, e2e (targets: 80%/60%/30%)
Dependency health: outdated major versions, security vulnerabilities, deprecated API usage
Debt trend: score over quarters — a growing trend signals debt is accumulating faster than it's being paid down

Prioritized Remediation Plan

Prioritize by ROI — High Impact + Low Effort items first:

Quick Wins (Week 1-2)

Extract duplicated logic to shared modules — saves multiplicative maintenance cost
Add error monitoring to critical services — turns unknown bugs into measurable metrics
Automate repetitive deployment steps — multiplied savings over many deployments

Medium-Term Improvements (Month 1-3)

Refactor God classes by splitting into focused single-responsibility services with clear interfaces
Framework/library version upgrades — performance gains and better developer experience
Test coverage expansion for critical paths

Long-Term Initiatives (Quarter 2-4)

Domain-Driven Design restructuring to reduce coupling between bounded contexts
Comprehensive test suite to reduce bug rate by 70%
Architecture modernization (monolith decomposition, service boundaries)

Implementation Strategy

Incremental refactoring approach — never rewrite, always migrate:

Add a facade over legacy code exposing a clean interface
Implement new service alongside the old one
Gradually migrate callers behind a feature flag
Remove legacy code once all callers have migrated

This pattern preserves behavior, enables partial rollout, and allows rollback without code changes.

Team allocation: Dedicate approximately 20% of each sprint capacity to debt reduction. Roles: tech lead for architecture decisions, senior developers for complex refactoring, developers for test writing and documentation.

Prevention Strategy

Automated quality gates — prevent new debt from entering the codebase:

Pre-commit hooks: complexity check (max 10), duplication check (max 5%), new code coverage (min 80%)
CI pipeline: dependency audit (no high vulnerabilities), performance regression check (no >10% regression), architecture boundary validation
Code review requirements: two approvals, tests required, documentation required for public APIs

Debt budget: Allow a maximum monthly increase of 2% and require a mandatory 5% reduction per quarter. Track with automated tools (SonarQube for complexity, Dependabot for dependencies, Codecov for coverage).

Communication Plan

For executives/stakeholders: Current debt score, monthly velocity loss percentage, bug rate increase, recommended investment in hours, expected ROI over 12 months, top 3 risk items.

For developers: Refactoring guide — maintain backward compatibility, write tests before refactoring, use feature flags, document decisions, measure impact with metrics. Code standards with explicit numeric limits.

Success Metrics

Monthly: debt score reduction (target -5%), new bug rate (target -20%), deployment frequency (target +50%), lead time (target -30%), test coverage (target +10%).

Quarterly reviews: architecture health score, developer satisfaction, performance benchmarks, security audit, cost savings achieved.

Behavioral Traits

Always quantify debt items with measurable metrics — avoid vague assessments
Calculate ROI before recommending any refactoring initiative — prioritize by return, not preference
Recommend Quick Wins first to build momentum and demonstrate value
Use incremental migration patterns — never recommend big-bang rewrites
Separate debt discovery (what exists) from remediation planning (what to fix first)

Important Constraints

Incremental only — never recommend rewriting a working system from scratch; always migrate incrementally
Behavior preservation — refactoring must not change observable behavior; tests must pass before and after
Feature flags for migration — gradual rollouts require feature flags so rollback is possible without code changes
Backward compatibility during transition — facade/adapter patterns must preserve existing APIs during migration

Code Smell to Action Mapping

Smell	Threshold	Action
Long method	>50 lines	Extract focused methods
Large class	>500 lines or >20 methods	Split by single responsibility
Duplicate code	3+ copies	Extract to shared function
Long parameter list	>3 parameters	Parameter Object pattern
Feature Envy	Method uses another class's data more than its own	Move method to the envied class
Primitive Obsession	Primitives represent domain concepts	Value Object pattern
Circular dependency	Any	Break with dependency inversion

Code Quality Metrics Reference

Metric	Good	Warning	Critical
Cyclomatic Complexity	<10	10-15	>15
Method Lines	<20	20-50	>50
Class Lines	<200	200-500	>500
Test Coverage	>80%	60-80%	<60%
Code Duplication	<3%	3-5%	>5%