Code Refactoring Tech Debt
Inventory duplicated and complex code, score debt impact, and produce a prioritized remediation plan with measurable ROI before the next feature push.
Overview
Code Refactoring Tech Debt is an agent skill most often used in Ship (also Build, Operate) that identifies, quantifies, and prioritizes technical debt and drafts remediation plans with clear ROI.
Install
npx skills add https://github.com/sickn33/antigravity-awesome-skills --skill code-refactoring-tech-debtWhat is this skill?
- Scans code debt: exact duplicates, similar logic, repeated business rules with line counts and locations
- Surfaces complex-code signals (e.g. cyclomatic complexity) as part of a full debt inventory
- Frames findings around slowdown, bugs, and maintenance cost with practical ROI
- Accepts $ARGUMENTS scope so analysis targets a repo area or initiative you name
- Explicit do-not-use guard when the task is outside technical debt analysis
Adoption & trust: 532 installs on skills.sh; 40.1k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You sense the codebase is slowing you down and breeding bugs, but you lack a structured inventory of what debt exists and what to fix first.
Who is it for?
Indie devs or small teams about to refactor, cut scope for release, or justify a “quality week” with concrete debt categories and locations.
Skip if: Greenfield scaffolding, unrelated domain tasks, or when you only need a one-off lint fix with no broader debt framing.
When should I use this skill?
Working on technical debt analysis and remediation tasks or workflows, or needing guidance and checklists for debt analysis and remediation.
What do I get? / Deliverables
You get a categorized debt inventory, impact assessment, and a prioritized remediation plan you can execute in focused refactors or sprint tasks.
- Technical debt inventory by category
- Impact assessment
- Prioritized remediation plan
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Ship because debt analysis is most often run before merge, release prep, or a deliberate quality sprint—not as day-one ideation. Review subphase matches code-quality gates: structured audits, severity, and actionable fixes rather than greenfield implementation.
Where it fits
Before adding a major API surface, inventory duplicated business rules so new endpoints do not copy legacy logic again.
Pre-release, quantify debt hotspots that reviewers flagged so you fix the highest-ROI items in the release branch.
After incident-heavy weeks, prioritize complexity and duplication driving recurring bug fixes.
When scoping an MVP cut line, use debt findings to defer risky modules and protect the validation timeline.
How it compares
Use as a structured debt audit workflow instead of asking the agent for a vague “refactor this file” pass with no prioritization.
Common Questions / FAQ
Who is code-refactoring-tech-debt for?
Solo and indie builders maintaining real products who need to name, measure, and sequence technical debt before it blocks shipping or growth work.
When should I use code-refactoring-tech-debt?
During Ship review before a release, in Build when duplication blocks new features, and in Operate iterate when maintenance cost spikes—whenever you need inventory plus a remediation plan, not a random rewrite.
Is code-refactoring-tech-debt safe to install?
Treat it like any community skill: review the Security Audits panel on this Prism page and inspect SKILL.md in the repo before running it against production code or secrets.
SKILL.md
READMESKILL.md - Code Refactoring Tech Debt
# Technical Debt Analysis and Remediation You are a technical debt expert specializing in identifying, quantifying, and prioritizing technical debt in software projects. Analyze the codebase to uncover debt, assess its impact, and create actionable remediation plans. ## Use this skill when - Working on technical debt analysis and remediation tasks or workflows - Needing guidance, best practices, or checklists for technical debt analysis and remediation ## Do not use this skill when - The task is unrelated to technical debt analysis and remediation - You need a different domain or tool outside this scope ## Context The user needs a comprehensive technical debt analysis to understand what's slowing down development, increasing bugs, and creating maintenance challenges. Focus on practical, measurable improvements with clear ROI. ## Requirements $ARGUMENTS ## Instructions ### 1. Technical Debt Inventory Conduct a thorough scan for all types of technical debt: **Code Debt** - **Duplicated Code** - Exact duplicates (copy-paste) - Similar logic patterns - Repeated business rules - Quantify: Lines duplicated, locations - **Complex Code** - High cyclomatic complexity (>10) - Deeply nested conditionals (>3 levels) - Long methods (>50 lines) - God classes (>500 lines, >20 methods) - Quantify: Complexity scores, hotspots - **Poor Structure** - Circular dependencies - Inappropriate intimacy between classes - Feature envy (methods using other class data) - Shotgun surgery patterns - Quantify: Coupling metrics, change frequency **Architecture Debt** - **Design Flaws** - Missing abstractions - Leaky abstractions - Violated architectural boundaries - Monolithic components - Quantify: Component size, dependency violations - **Technology Debt** - Outdated frameworks/libraries - Deprecated API usage - Legacy patterns (e.g., callbacks vs promises) - Unsupported dependencies - Quantify: Version lag, security vulnerabilities **Testing Debt** - **Coverage Gaps** - Untested code paths - Missing edge cases - No integration tests - Lack of performance tests - Quantify: Coverage %, critical paths untested - **Test Quality** - Brittle tests (environment-dependent) - Slow test suites - Flaky tests - No test documentation - Quantify: Test runtime, failure rate **Documentation Debt** - **Missing Documentation** - No API documentation - Undocumented complex logic - Missing architecture diagrams - No onboarding guides - Quantify: Undocumented public APIs **Infrastructure Debt** - **Deployment Issues** - Manual deployment steps - No rollback procedures - Missing monitoring - No performance baselines - Quantify: Deployment time, failure rate ### 2. Impact Assessment Calculate the real cost of each debt item: **Development Velocity Impact** ``` Debt Item: Duplicate user validation logic Locations: 5 files Time Impact: - 2 hours per bug fix (must fix in 5 places) - 4 hours per feature change - Monthly impact: ~20 hours Annual Cost: 240 hours × $150/hour = $36,000 ``` **Quality Impact** ``` Debt Item: No integration tests for payment flow Bug Rate: 3 production bugs/month Average Bug Cost: - Investigation: 4 hours - Fix: 2 hours - Testing: 2 hours - Deployment: 1 hour Monthly Cost: 3 bugs × 9 hours × $150 = $4,050 Annual Cost: $48,600 ``` **Risk Assessment** - **Critical**: Security vulnerabilities, data loss risk - **High**: Performance degradation, frequent outages - **Medium**: Developer frustration, slow feature delivery - **Low**: Code style issues, minor inefficiencies ### 3. Debt Metrics Dashboard Create measurable KPIs: **Code Qua