| name | technical-debt |
| description | Technical Debt: Identification, prioritization, payoff strategy, prevention. |
| triggers | {"keywords":["refactor","technical debt","cleanup","legacy","TODO","FIXME","complexity","coupling"]} |
| auto_load_when | Addressing technical debt or refactoring |
| agent | architect |
| tools | ["Read","Write","Bash"] |
Technical Debt Patterns
Focus: Managing, prioritizing, reducing debt over time
1. What is Technical Debt
Debt types:
├── Code debt (poor code quality)
├── Architecture debt (bad structure)
├── Test debt (low coverage)
├── Documentation debt (missing docs)
├── Infrastructure debt (outdated ops)
Origin:
├── Shortcuts for speed
├── Missing knowledge
├── Time pressure
└── Abandoned experiments
2. Identification
Signs of debt:
├── Feature development slows
├── Bugs increase
├── Onboarding time grows
├── Tests are flaky
├── Fear to change code
└── CircleCI takes forever
Tools:
├── Code coverage
├── Complexity metrics
├── Code review patterns
└── Team retrospective
3. Prioritization
Factors to consider:
├── Impact on development speed
├── Risk level
├── Effort to fix
├── Dependencies
└── Business value
Prioritize:
├── High impact, low effort first
├── Critical paths over edge cases
└── Infrastructure before features
4. Payoff Strategies
Strategies:
├── Dedicated "debt Friday"
├── Include in estimates
├── Boy scout rule (leave better)
├── Rewrite vs refactor
└── Feature work includes cleanup
Better: Prevent than fix
5. Measurement
Metrics:
├── Cyclomatic complexity
├── Coupling (imports)
├── Test coverage %
├── Time to run tests
├── Build times
Track over time to see trends
6. Communication
To stakeholders:
├── Show impact on velocity
├── Estimate slowdown %
├── Link to bugs/delays
└── Propose investment
Not: "Code is bad, we should fix"
Yes: "Cleanup gives 20% velocity boost"
7. Prevention
Prevent debt:
├── Code standards + linter
├── Pull request reviews
├── Test requirements (80%+)
├── Architecture review
├── Pair programming
└── Technical spikes before stories
Key Patterns
- Track - visible backlog
- Prioritize - impact vs effort
- Prevent - standards + review
- Communicate - business value
- Pay regularly - small batches
(End of file - 77 lines)
Anti-Patterns
❌ "We'll fix it later" with no ticket created
✅ Log all debt immediately with TODO + ticket reference
❌ Paying all debt in one big refactor sprint
✅ Boy Scout Rule — leave code cleaner than you found it
❌ Ignoring debt until it causes an outage
✅ Track debt metric (complexity, coverage) in CI
❌ Rewriting everything instead of targeted refactors
✅ Strangler Fig: replace incrementally, keep working at all times
❌ Debt that no one owns
✅ Each debt item has an assigned owner and deadline
Quick Reference
| Debt type | Detection | Remedy |
|---|
| Design debt | Arch review, complexity score | Targeted refactor |
| Code debt | High cyclomatic complexity | Extract + simplify |
| Test debt | Low coverage, flaky tests | Add tests before feature |
| Dependency debt | Outdated/vulnerable packages | Dependency sentinel |
| Documentation debt | No README, stale docs | docs-agent |
| Performance debt | CWV regressions | Perf audit + fix |
🌍 Universal Language Support
- Turkish Native: This skill natively supports Turkish. If the user prompt is in Turkish, all analysis, formatting, and output MUST be entirely in Turkish. You do not need explicit "write in Turkish" instructions.
