tech-debt-analyzer

Technical Debt Analyzer

Overview

Systematically identify, analyze, document, and track technical debt in JavaScript/TypeScript codebases. This skill provides automated analysis tools, comprehensive debt categorization frameworks, and documentation templates to maintain a technical debt register.

Core Workflow

1. Automated Analysis

Run automated scripts to detect technical debt indicators across the codebase.

Code Smell Detection

Identify code quality issues using the automated detector:

python3 scripts/detect_code_smells.py src --output markdown

The script analyzes:

• Large Files: Files exceeding 500 lines
• Complex Functions: High cyclomatic complexity (>10) or long functions (>50 lines)
• Debt Markers: TODO, FIXME, HACK, XXX, BUG comments
• Console Statements: Debug statements left in code
• Weak Typing: Use of any type in TypeScript
• Long Parameters: Functions with >5 parameters
• Deep Nesting: Code nested >4 levels deep
• Magic Numbers: Hardcoded numeric values

Output Example:

# Technical Debt Analysis Report

**Files Analyzed:** 127
**Total Lines:** 15,432
**Total Issues:** 89

### Issues by Severity
- HIGH: 23
- MEDIUM: 41
- LOW: 25

## Large Files (12 issues)
### High Priority
- src/components/Dashboard.tsx (847 lines): File too large
- src/services/DataProcessor.ts (623 lines): File too large
...

Dependency Analysis

Examine dependencies for debt indicators:

python3 scripts/analyze_dependencies.py package.json

The script identifies:

• Deprecated Packages: Known deprecated libraries (request, tslint, etc.)
• Duplicate Functionality: Multiple packages serving same purpose
• Version Issues: Overly loose or strict version constraints
• Security Concerns: Known vulnerable packages (requires audit data)

Output Example:

# Dependency Analysis Report

**Package:** expense-tracker
**Dependencies:** 24
**Dev Dependencies:** 18
**Total Issues:** 7

## Deprecated/Outdated Packages (3)
### request [HIGH]
Using deprecated package - use axios, node-fetch, or got instead
- Current version: ^2.88.0

## Duplicate Functionality (2)
### HTTP client [MEDIUM]
Multiple packages for HTTP client: axios, node-fetch

2. Manual Code Review

Complement automated analysis with manual review for issues that require human judgment.

Review Focus Areas

Architectural Debt:

• Tight coupling between components
• Missing abstractions
• Poor separation of concerns
• Circular dependencies

Test Debt:

• Missing test coverage for critical paths
• Fragile tests coupled to implementation
• No integration or E2E tests
• Slow test execution

Documentation Debt:

• Missing README or setup instructions
• No architecture documentation
• Outdated API docs
• Missing ADRs for major decisions

Performance Debt:

• N+1 query problems
• Inefficient algorithms
• Memory leaks
• Large bundle sizes

Security Debt:

• Missing input validation
• No authentication/authorization
• SQL injection vulnerabilities
• XSS vulnerabilities
• Exposed secrets

3. Categorize and Assess

Organize findings using the standardized debt categories.

Debt Categories

Refer to references/debt_categories.md for comprehensive details on:

1. Code Quality Debt: Code smells, complexity, duplication
2. Architectural Debt: Structure, coupling, abstractions
3. Test Debt: Coverage gaps, fragile tests
4. Documentation Debt: Missing or outdated docs
5. Dependency Debt: Outdated or problematic dependencies
6. Performance Debt: Inefficiencies and bottlenecks
7. Security Debt: Vulnerabilities and weaknesses
8. Infrastructure Debt: DevOps and deployment issues
9. Design Debt: UI/UX inconsistencies

Severity Assessment

Assign severity based on impact and urgency:

Critical:

• Security vulnerabilities
• Production-breaking issues
• Data loss risks
• Action: Immediate fix required

High:

• Significant performance problems
• Architectural issues blocking features
• High-risk untested code
• Action: Fix within current/next sprint

Medium:

• Code quality issues in frequently changed files
• Missing documentation
• Outdated dependencies (non-security)
• Action: Address within quarter

Low:

• Minor code smells
• Optimization opportunities
• Nice-to-have improvements
• Action: Address when convenient

Priority Matrix

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

4. Document Findings

Create comprehensive documentation of technical debt.

Technical Debt Register

Use the provided template to maintain a debt register:

Template Location: assets/DEBT_REGISTER_TEMPLATE.md

Structure:

## DEBT-001: Complex UserService with 847 lines

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

**Description:**
UserService has grown to 847 lines with multiple responsibilities
including authentication, profile management, and notification handling.

**Impact:**
- Business: Slows down feature development by 30%
- Technical: Difficult to test, high bug rate
- Risk: Changes frequently break unrelated functionality

**Proposed Solution:**
Split into separate services:
- AuthenticationService
- UserProfileService
- NotificationService

**Effort Estimate:** 3 days
**Priority Justification:** High churn area blocking new features
**Target Resolution:** Sprint 24

Register Sections:

1. Active Debt Items: Current technical debt needing attention
2. Resolved Items: Historical record of fixed debt
3. Won't Fix Items: Debt accepted as acceptable trade-off
4. Trends: Analysis by category, severity, and age
5. Review Schedule: Regular maintenance plan

Architecture Decision Records (ADRs)

Document major technical decisions using ADRs to prevent future debt.

Template Location: assets/ADR_TEMPLATE.md

When to Create ADRs:

• Choosing frameworks or libraries
• Architectural changes
• Major refactoring decisions
• Technology migrations
• Performance optimization strategies

Example:

# ADR-003: Migrate from Moment.js to date-fns

**Status:** Accepted
**Date:** 2024-01-15

## Context
Moment.js is deprecated and increases bundle size by 67KB.
Team needs a modern date library with tree-shaking support.

## Decision
Migrate to date-fns for date manipulation.

## Consequences
- Positive: Reduce bundle by 60KB, modern API, active maintenance
- Negative: Migration effort, learning curve for team
- Technical Debt: None - this resolves existing dependency debt

5. Prioritize and Plan

Create actionable plans to address technical debt.

Prioritization Approach

1. Critical Items: Add to current sprint immediately
2. High Items: Include in sprint planning
3. Medium Items: Add to quarterly roadmap
4. Low Items: Opportunistic fixes during related work

Time Allocation

Recommended Allocation:

• 20% of sprint capacity for technical debt
• Alternating sprints: feature sprint / debt sprint
• Dedicated quarterly "tech health" sprint

Tracking Progress

Monitor debt reduction over time:

Metrics to Track:

• Total debt items (trend down)
• Debt by severity (critical should be 0)
• Debt age (old debt is concerning)
• Resolution rate (items fixed per sprint)
• New debt rate (items added per sprint)

6. Prevention Strategies

Implement practices to minimize new technical debt.

Code Review Checklist

Before approving PRs, verify:

• No code smells introduced (complexity, size, nesting)
• Tests added/updated with adequate coverage
• Documentation updated (README, comments, ADRs)
• No security vulnerabilities
• Performance impact considered
• No new dependencies without justification
• Follows team conventions and patterns

Automated Prevention

Linting and Formatting:

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

Required Checks:

• TypeScript strict mode enabled
• Minimum test coverage threshold (80%)
• No high-severity security vulnerabilities
• Bundle size limits enforced

Regular Maintenance

Weekly:

• Review and triage TODO/FIXME comments
• Update debt register with new findings

Monthly:

• Dependency updates (security patches)
• Debt register review
• Plan fixes for high-priority items

Quarterly:

• Full codebase debt analysis
• Architecture review
• Major dependency updates
• Trend analysis and strategy adjustment

Decision Tree

Follow this workflow based on the situation:

Starting a new analysis? → Run automated scripts (detect_code_smells.py, analyze_dependencies.py) → Review output for high-severity issues → Conduct manual review for areas scripts can't detect → Go to documentation step

Documenting findings? → Copy DEBT_REGISTER_TEMPLATE.md to project root → Add each debt item with full details → Categorize by type and assign severity → Estimate effort and prioritize → Go to planning step

Planning debt reduction? → Sort by priority matrix (impact/effort) → Allocate sprint capacity (20% recommended) → Create tickets for top priority items → Schedule regular reviews

Making architectural decisions? → Copy ADR_TEMPLATE.md → Document context, options, and decision → Identify any debt being incurred → Add to debt register if applicable

Preventing new debt? → Implement code review checklist → Configure automated linting/testing → Set up regular maintenance schedule → Monitor metrics over time

Tools and Scripts

detect_code_smells.

---

Content truncated.