tech-debt-analyzer

Technical Debt Analyzer

Systematically identify, analyze, and document technical debt.

When to Use

Use for:

• Analyzing code quality issues
• Creating technical debt registers
• Assessing code maintainability
• Identifying dependency problems
• Documenting security vulnerabilities
• Planning refactoring efforts

Don't use when:

• Writing new code → use generic-feature-developer
• Code review → use generic-code-reviewer
• Writing tests → use test-specialist

Quick Analysis Commands

# Find large files (>500 lines)
find src -name "*.ts" -exec wc -l {} + | awk '$1 > 500' | sort -rn

# Find TODO/FIXME markers
grep -rn "TODO\|FIXME\|HACK\|XXX" src/

# Check for console.log in production code
grep -rn "console.log" src/ --include="*.ts" --include="*.tsx"

# Find TypeScript 'any' usage
grep -rn ": any" src/ --include="*.ts" --include="*.tsx"

# Check outdated dependencies
npm outdated

# Security vulnerabilities
npm audit

# Unused exports (requires ts-unused-exports)
npx ts-unused-exports tsconfig.json

Debt Categories

Analysis Workflow

1. Automated Detection

Code Smells to Check:

• Large files (>500 lines)
• Complex functions (cyclomatic complexity >10)
• Debt markers (TODO, FIXME, HACK, XXX)
• Console statements in production code
• any types in TypeScript
• Long parameter lists (>5 params)
• Deep nesting (>4 levels)

Dependency Issues:

• Deprecated packages
• Duplicate functionality
• Loose version constraints
• Known vulnerabilities

2. Severity Assessment

3. Priority Matrix

Debt Register Format

## DEBT-001: Description

**Category:** Code Quality | **Severity:** High
**Location:** src/services/UserService.ts

**Description:** Brief description of the issue

**Impact:**

- Business: How it affects delivery
- Technical: Why it's problematic
- Risk: What could go wrong

**Proposed Solution:** What to do about it
**Effort:** Days/hours estimate
**Target:** Sprint/quarter

Prevention Strategies

Automated Guards

{
  "rules": {
    "complexity": ["error", 10],
    "max-lines-per-function": ["error", 50],
    "max-params": ["error", 5],
    "max-depth": ["error", 4]
  }
}

Maintenance Schedule

Self-Critique Checklist

After completing debt analysis:

• [ ] All automated checks run
• [ ] Manual review of critical paths done
• [ ] Severity assessments justified
• [ ] Proposed solutions are actionable
• [ ] Priority matrix applied consistently
• [ ] Register entries are complete

See Also

• Code Review Standards - Quality checks
• Project CLAUDE.md - Workflow rules