| name | technical-debt-assessment |
| description | Audits a codebase or architecture for technical debt. Identifies code smells, architectural anti-patterns, scalability risks, and maintenance burden. Outputs a prioritized debt registry with refactoring recommendations and effort estimates. |
| allowed-tools | Read |
| effort | medium |
Technical Debt Assessment
When to activate
When taking over a system that's been in production for 6+ months, or when performance/reliability concerns emerge. Triggered by: postmortem after incident, customer complaint about speed/crashes, developer request for refactoring time, migration planning, or periodic health check (quarterly). Can be run on entire codebase or specific modules.
When NOT to use
Not for greenfield projects (there's no debt yet). Not as code review (that's line-level analysis). Not for performance optimization alone (use performance-tuning instead). Not if no access to code or architecture (request access first). Not if the system is already being decommissioned.
Audit Checklist
Code Quality
Architecture & Design
Data & Databases
Operations & Monitoring
Security & Compliance
Dependencies
Output Format
Technical Debt Registry
Executive Summary
- Overall health: HEALTHY / AT RISK / CRITICAL
- Debt-to-value ratio: [estimate: how much effort to refactor vs. feature work]
- Top 3 risks: [What will bite us hardest]
- Recommended action: [MAINTAIN / REFACTOR INCREMENTALLY / REWRITE]
Debt by Category
| Category | Severity | Count | Impact | Est. Effort |
|---|
| Code Quality | HIGH | 12 | Bugs, slow development | 8 weeks |
| Architecture | CRITICAL | 3 | Scaling blocked | 16 weeks |
| Data | MEDIUM | 5 | Performance issues | 3 weeks |
| Operations | HIGH | 8 | Reliability risk | 4 weeks |
| Security | CRITICAL | 2 | Breach risk, compliance | 2 weeks |
| Dependencies | MEDIUM | 23 | Supply chain risk | 1 week |
Detailed Findings
By severity (CRITICAL first, then HIGH, MEDIUM):
- [Finding Title]
- Severity: CRITICAL
- Location: [File, class, module]
- Description: [What's wrong]
- Impact: [Why it matters — reliability, security, performance, dev velocity]
- Recommendation: [How to fix — refactor, rewrite, replace]
- Effort: [S/M/L/XL]
- Blocker for: [What feature/goal is blocked by this]
Example:
1. No Authentication in Legacy Admin API
Severity: CRITICAL
Location: /api/admin/*
Description: Admin endpoints have no auth — anyone can access with correct URL
Impact: Security breach risk. Customer data exposed.
Recommendation: Add OAuth2 + role-based access control. Audit all endpoints.
Effort: L (2 weeks)
Blocker for: Production deployment, SOC2 certification
Refactoring Roadmap
Phase 1 (Now–4 weeks): CRITICAL security and reliability fixes
Phase 2 (Weeks 4–12): HIGH priority, high-impact refactoring
Phase 3+ (Months 3+): MEDIUM priority, incremental improvements
Prevention Plan (so debt doesn't accumulate again)
