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

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