# Technical Debt Assessment

> 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.

- Skill: `uitbreidenos/technical-debt-assessment` (Agent Skill)
- Install (CLI): `npx skillmds@latest add uitbreidenos/technical-debt-assessment`
- Raw SKILL.md: https://api.skillmd.com/api/skills/uitbreidenos/technical-debt-assessment/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: UitbreidenOS (https://skillmd.com/u/uitbreidenos)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/uitbreidenos/technical-debt-assessment

---


# 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**
- [ ] Code duplication (DRY violations)
- [ ] Long methods/functions (>50 lines)
- [ ] God classes (>500 lines, >10 responsibilities)
- [ ] Tight coupling (high fan-in/fan-out)
- [ ] Missing abstractions (repeated patterns)
- [ ] Test coverage <80%?
- [ ] No logging/instrumentation?
- [ ] Deprecated language features still in use?

**Architecture & Design**
- [ ] Circular dependencies between modules?
- [ ] Monolithic components that should be split?
- [ ] Missing API versioning/contracts?
- [ ] Tech stack drift (multiple languages, frameworks)?
- [ ] No clear separation of concerns?
- [ ] Hard-coded configuration (no external config)?

**Data & Databases**
- [ ] Unindexed queries causing slowness?
- [ ] N+1 query patterns?
- [ ] Missing database constraints?
- [ ] Inadequate schema documentation?
- [ ] No data migration strategy?
- [ ] Backup/restore untested?

**Operations & Monitoring**
- [ ] No centralized logging?
- [ ] No alerting on critical errors?
- [ ] Manual deployment (no CI/CD)?
- [ ] No staging environment?
- [ ] Runbooks missing or outdated?
- [ ] No load testing or capacity planning?

**Security & Compliance**
- [ ] Hardcoded secrets in code?
- [ ] No input validation?
- [ ] Missing auth/authz checks?
- [ ] Outdated dependencies (vulnerable)?
- [ ] No encryption in transit or at rest?
- [ ] Compliance requirements unmet?

**Dependencies**
- [ ] Outdated libraries (security patches missing)?
- [ ] Unused dependencies (bloat)?
- [ ] Breaking changes in minor versions?
- [ ] Missing dependency lock files?

## 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):

1. **[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
- [Fix 1]
- [Fix 2]

Phase 2 (Weeks 4–12): HIGH priority, high-impact refactoring
- [Fix 3]
- [Fix 4]

Phase 3+ (Months 3+): MEDIUM priority, incremental improvements
- [Fix 5]
- [Fix 6]

**Prevention Plan** (so debt doesn't accumulate again)

- [ ] Code review checklist updated
- [ ] Automated linting/testing in CI/CD
- [ ] Dependency scanning (Dependabot, Snyk)
- [ ] Quarterly architecture review
- [ ] Tech lead review before major changes
- [ ] Developer training on best practices

---