Skill: Technical Debt Management (Cross-Cutting)
Purpose
Systematically identify, categorize, and prioritize technical debt to manage codebase maintenance and refactoring.
When to Use
- When conducting code health/quality audits
- When preparing refactoring proposals
- When managing maintenance backlogs or prioritizing code quality tasks alongside feature work
Step-by-Step Process
Step 1: Identify and Categorize
- Code debt: Duplicated logic, poor abstractions, magic numbers, lack of type safety
- Architecture debt: Tight coupling, monolith splitting needs, wrong database choices
- Test debt: Low coverage, flaky tests, missing integration/E2E test pipelines
- Dependency debt: Outdated libraries, unmaintained packages, security vulnerabilities
- Documentation debt: Outdated READMEs, missing runbooks, undocumented APIs
Step 2: Evaluate and Score
Score each item on a 1-5 scale:
- Impact: How much does it slow the development team down? (1-5)
- Risk: What is the likelihood and impact of failure if left unresolved? (1-5)
- Effort: How difficult/expensive is it to fix? (1-5)
Step 3: Prioritize
Calculate the priority score using the formula:
Priority = (Impact + Risk) x (6 - Effort)
(Note: A lower effort value increases the priority score).
Step 4: Plan Remediation
- Organize prioritized items into a phased remediation backlog
- Propose refactoring phases that can run incrementally alongside regular feature implementation
Required Input
- Codebase access or architectural description
- History of recent outages, deployment issues, or developer complaints
Expected Output
- Prioritized technical debt registry including:
- Technical debt category and description
- Impact, Risk, Effort scores, and Priority calculation
- Business justification for refactoring
- Phased remediation plan
Tone & Rules
- Avoid subjective complaints. Focus on quantifiable metrics (developer velocity, test failures).
- Frame refactoring in terms of business value (reduced latency, faster onboarding, lower crash rate).
Available Templates
Available Scripts
Examples
See examples/ directory.
Links to Other Skills
- suggestion: Use to turn tech debt findings into actionable feature suggestions.
- sourcecode-analyzer: Use to automate finding duplicated code and quality violations.
1---2name: tech-debt3description: Skill: Technical Debt Management (Cross-Cutting)4---5# Skill: Technical Debt Management (Cross-Cutting)67## Purpose89Systematically identify, categorize, and prioritize technical debt to manage codebase maintenance and refactoring.1011## When to Use1213- When conducting code health/quality audits14- When preparing refactoring proposals15- When managing maintenance backlogs or prioritizing code quality tasks alongside feature work1617## Step-by-Step Process1819### Step 1: Identify and Categorize20- **Code debt**: Duplicated logic, poor abstractions, magic numbers, lack of type safety21- **Architecture debt**: Tight coupling, monolith splitting needs, wrong database choices22- **Test debt**: Low coverage, flaky tests, missing integration/E2E test pipelines23- **Dependency debt**: Outdated libraries, unmaintained packages, security vulnerabilities24- **Documentation debt**: Outdated READMEs, missing runbooks, undocumented APIs2526### Step 2: Evaluate and Score27Score each item on a 1-5 scale:28- **Impact**: How much does it slow the development team down? (1-5)29- **Risk**: What is the likelihood and impact of failure if left unresolved? (1-5)30- **Effort**: How difficult/expensive is it to fix? (1-5)3132### Step 3: Prioritize33Calculate the priority score using the formula:34`Priority = (Impact + Risk) x (6 - Effort)`35*(Note: A lower effort value increases the priority score).*3637### Step 4: Plan Remediation38- Organize prioritized items into a phased remediation backlog39- Propose refactoring phases that can run incrementally alongside regular feature implementation4041## Required Input4243- Codebase access or architectural description44- History of recent outages, deployment issues, or developer complaints4546## Expected Output4748- Prioritized technical debt registry including:49 - Technical debt category and description50 - Impact, Risk, Effort scores, and Priority calculation51 - Business justification for refactoring52 - Phased remediation plan5354## Tone & Rules5556- Avoid subjective complaints. Focus on quantifiable metrics (developer velocity, test failures).57- Frame refactoring in terms of business value (reduced latency, faster onboarding, lower crash rate).5859## Available Templates6061- None6263## Available Scripts6465- None6667## Examples6869See `examples/` directory.7071## Links to Other Skills7273- **suggestion**: Use to turn tech debt findings into actionable feature suggestions.74- **sourcecode-analyzer**: Use to automate finding duplicated code and quality violations.
PolyXGO