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

| Category | Examples | | ------------- | ------------------------------------------------------ | | Code Quality | Large files, complex functions, TODO/FIXME markers | | Architectural | Tight coupling, missing abstractions, circular deps | | Test | Missing coverage, fragile tests, slow execution | | Documentation | Missing README, outdated docs, no ADRs | | Dependency | Outdated packages, security vulnerabilities | | Performance | N+1 queries, memory leaks, large bundles | | Security | Missing validation, exposed secrets, XSS/SQL injection |

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

| Severity | Criteria | Action | | -------- | ------------------------------------- | --------------- | | Critical | Security vulns, data loss risk | Immediate fix | | High | Performance problems, blocking issues | Current sprint | | Medium | Code quality, missing docs | This quarter | | Low | Minor smells, optimizations | When convenient |

3. Priority Matrix

| Impact / Effort | Low | Medium | High | | --------------- | --------- | --------- | --------- | | High Impact | Do First | Do Second | Plan & Do | | Medium Impact | Do Second | Plan & Do | Consider | | Low Impact | Quick Win | Consider | Avoid |

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

| Frequency | Tasks | | --------- | ---------------------------------- | | Weekly | Review TODO/FIXME, update register | | Monthly | Dependency updates, debt review | | Quarterly | Full analysis, architecture review |

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