technical-debt-assessment_skill

Overview

This skill assesses, quantifies, and prioritizes technical debt across code, tests, architecture, documentation, security, and performance. It combines static code scanning, quantitative metrics, and impact/effort modeling to produce actionable prioritized lists and reports. Use it to guide refactoring, sprint planning, or architectural choices with a clear ROI focus.

How this skill works

The skill scans repositories for quality issues and anti-patterns, assigns estimated remediation effort and debt hours, and categorizes findings (code, architecture, test, documentation, security, performance). It applies a priority formula that weights impact, ongoing interest (cost of not fixing), severity, and effort to rank items. It generates summaries, category breakdowns, top-priority items, and estimated total effort and monthly interest to support decision making.

When to use it

• Evaluating legacy code before a major release or migration
• Prioritizing work when planning refactorings or backlog grooming
• Estimating effort and ROI for technical debt remediation in sprint planning
• Due diligence during acquisitions or when onboarding a new codebase
• Setting or enforcing quality gates and tracking debt over time

Best practices

• Quantify both one-time effort and recurring interest to compare ROI
• Prioritize fixes by impact per hour rather than severity alone
• Keep a running debt register and track changes across releases
• Allocate a fixed percentage of each sprint to high-priority debt
• Document rationale for leaving or addressing each debt item

Example use cases

• Run a project scan to list missing tests, long functions, and magic numbers with estimated debt hours
• Produce a prioritized remediation plan for legacy API endpoints affecting multiple services
• Estimate total effort and monthly interest to justify a refactor to stakeholders
• Integrate into sprint planning to schedule high-ROI debt fixes alongside feature work
• Use reports during acquisition reviews to quantify maintenance risk and roadmap impact