tech-debt
npx machina-cli add skill anthropics/knowledge-work-plugins/tech-debt --openclawTech Debt Management
Systematically identify, categorize, and prioritize technical debt.
Categories
| Type | Examples | Risk |
|---|---|---|
| Code debt | Duplicated logic, poor abstractions, magic numbers | Bugs, slow development |
| Architecture debt | Monolith that should be split, wrong data store | Scaling limits |
| Test debt | Low coverage, flaky tests, missing integration tests | Regressions ship |
| Dependency debt | Outdated libraries, unmaintained dependencies | Security vulns |
| Documentation debt | Missing runbooks, outdated READMEs, tribal knowledge | Onboarding pain |
| Infrastructure debt | Manual deploys, no monitoring, no IaC | Incidents, slow recovery |
Prioritization Framework
Score each item on:
- Impact: How much does it slow the team down? (1-5)
- Risk: What happens if we don't fix it? (1-5)
- Effort: How hard is the fix? (1-5, inverted — lower effort = higher priority)
Priority = (Impact + Risk) x (6 - Effort)
Output
Produce a prioritized list with estimated effort, business justification for each item, and a phased remediation plan that can be done alongside feature work.
Source
git clone https://github.com/anthropics/knowledge-work-plugins/blob/main/engineering/skills/tech-debt/SKILL.mdView on GitHub Overview
Tech Debt Management identifies, categorizes, and prioritizes debt across code, architecture, test, dependency, documentation, and infrastructure. It uses a simple scoring model to surface the most impactful work and deliver a phased remediation plan that can run alongside new features.
How This Skill Works
Create a living inventory of debt items in the six categories. Score each item on Impact, Risk, and Effort (1-5) and compute Priority with Priority = (Impact + Risk) x (6 - Effort). Produce a prioritized list with estimated effort, business justification, and a phased remediation plan aligned to feature work.
When to Use It
- Triggered by phrases like 'tech debt' or 'technical debt audit' to start a formal debt review.
- When someone asks 'what should we refactor' or seeks refactoring guidance based on observed debt.
- During conversations about code health, code quality, refactoring priorities, or the maintenance backlog.
- During backlog refinement to categorize items into code, architecture, test, dependency, documentation, or infrastructure debt for triage.
- In sprint or release planning to generate a phased remediation plan that can run alongside feature work.
Quick Start
- Step 1: Build a living inventory of debt items across code, architecture, tests, dependencies, docs, and infrastructure.
- Step 2: Score each item with Impact, Risk, and Effort (1-5) and compute Priority using Priority = (Impact + Risk) x (6 - Effort).
- Step 3: Output a prioritized list with estimated effort, business justification, and a phased remediation plan that aligns with feature work.
Best Practices
- Start with a comprehensive debt inventory covering all six categories.
- Score items using Impact, Risk, and Effort, and apply the Priority formula to rank work.
- Keep a living backlog with clear business justification and rough effort estimates.
- Align debt remediation with feature work and set quick wins to regain velocity.
- Regularly review and re-prioritize debt as risks and business needs evolve.
Example Use Cases
- Code debt: Duplicated logic and poor abstractions lead to bugs; refactor into shared utilities and cleaner interfaces as a phased task.
- Architecture debt: A monolith that should be split; plan modular boundaries or incremental extraction to reduce scaling risk.
- Test debt: Low test coverage and flaky tests; add high-value integration tests and stabilize the test suite.
- Dependency debt: Outdated libraries and unmaintained dependencies; upgrade with compatibility checks and a release plan.
- Documentation debt: Missing runbooks and outdated READMEs; create living docs to improve onboarding and incident response.
