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:

• Code Quality Debt: Code smells, complexity, duplication

• Architectural Debt: Structure, coupling, abstractions

• Test Debt: Coverage gaps, fragile tests

• Documentation Debt: Missing or outdated docs

• Dependency Debt: Outdated or problematic dependencies

• Performance Debt: Inefficiencies and bottlenecks

• Security Debt: Vulnerabilities and weaknesses

• Infrastructure Debt: DevOps and deployment issues

• 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:

• Active Debt Items: Current technical debt needing attention

• Resolved Items: Historical record of fixed debt

• Won't Fix Items: Debt accepted as acceptable trade-off

• Trends: Analysis by category, severity, and age

• 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

• Critical Items: Add to current sprint immediately

• High Items: Include in sprint planning

• Medium Items: Add to quarterly roadmap

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

Purpose: Automated code quality analysis

Usage:

python3 scripts/detect_code_smells.py [src-dir] [--output json|markdown]

Detects:

• Large files (>500 lines)

• Complex functions (complexity >10)

• Technical debt markers (TODO, FIXME, HACK)

• Console statements

• Weak TypeScript typing

• Long parameter lists (>5 params)

• Deep nesting (>4 levels)

• Magic numbers

Output: Markdown report or JSON for programmatic processing

analyze_dependencies.py

Purpose: Dependency health analysis

Usage:

python3 scripts/analyze_dependencies.py [package.json-path]

Detects:

• Deprecated packages (request, tslint, node-sass, etc.)

• Duplicate functionality (multiple date libs, http clients, etc.)

• Unsafe version constraints (*, latest)

• Overly strict versions (exact versions without ^ or ~)

Output: Markdown report with recommendations

Reference Documentation

debt_categories.md

Comprehensive guide to technical debt types with:

• 9 major debt categories

• Indicators and examples for each

• Impact assessment criteria

• Severity level definitions

• Measurement metrics

• Prevention strategies

Load this reference when:

• Need detailed examples of specific debt types

• Assessing severity and impact

• Understanding root causes

• Planning prevention strategies

Documentation Templates

DEBT_REGISTER_TEMPLATE.md

Complete technical debt register template including:

• Debt item structure

• Status tracking

• Impact assessment format

• Trend analysis sections

• Review schedule

Use this template to:

• Start a new debt register

• Standardize debt documentation

• Track debt across team/project

ADR_TEMPLATE.md

Architecture Decision Record template including:

• Context and problem statement

• Options considered

• Decision rationale

• Consequences (positive and negative)

• Implementation plan

Use this template to:

• Document major technical decisions

• Prevent future "why did we do this?" questions

• Track technical debt incurred by decisions

Best Practices

Analysis Best Practices

• Run analysis regularly (weekly or bi-weekly)

• Combine automated + manual review for comprehensive coverage

• Focus on high-churn areas first for maximum impact

• Involve the team in debt identification

• Be objective - all codebases have debt

Documentation Best Practices

• Be specific - include file names, line numbers, examples

• Explain impact - why does this matter?

• Propose solutions - don't just complain, suggest fixes

• Estimate effort - helps with prioritization

• Track trends - is debt increasing or decreasing?

Remediation Best Practices

• Fix critical items immediately - especially security

• Allocate consistent time - 20% of sprint capacity

• Celebrate wins - track and recognize debt reduction

• Don't let perfect be the enemy of good - incremental improvement

• Prevent new debt - easier than fixing old debt

Communication Best Practices

• Make debt visible - share metrics with stakeholders

• Educate on impact - connect debt to business outcomes

• Get buy-in - explain ROI of debt reduction

• Regular updates - include in sprint reviews

• Avoid blame - focus on improvement, not fault

Example Workflow

Complete workflow from analysis to resolution:

Week 1: Analysis

# Run automated analysis

python3 scripts/detect_code_smells.py src --output markdown > debt_analysis.md

python3 scripts/analyze_dependencies.py package.json >> debt_analysis.md

# Manual review of critical areas

# - Authentication logic

# - Payment processing

# - Data models

Week 1-2: Documentation

# Create debt register from template

cp assets/DEBT_REGISTER_TEMPLATE.md TECHNICAL_DEBT.md

# Add findings to register with:

# - Category and severity

# - Impact assessment

# - Effort estimation

# - Priority assignment

Week 2: Prioritization

# Team review session

# - Review all high/critical items

# - Discuss quick wins (high impact, low effort)

# - Allocate sprint capacity

# - Create tickets for top 5 items

Weeks 3-6: Remediation

# Sprint work

# - Fix 2-3 debt items per sprint

# - Update debt register as items resolved

# - Create ADRs for major refactoring decisions

# - Monitor metrics

Monthly: Review

# Trend analysis

# - Total debt (should decrease)

# - New debt rate (should be low)

# - Age of oldest items (should decrease)

# - Categories most affected

# Adjust strategy based on trends

Success Metrics

Track these metrics to measure debt reduction effectiveness:

Quantity Metrics:

• Total debt items (trending down)

• Debt by severity (zero critical)

• Debt items per 1000 LOC

Quality Metrics:

• Test coverage (trending up)

• Cyclomatic complexity (trending down)

• Average file/function size (stable or decreasing)

Velocity Metrics:

• Debt items resolved per sprint

• New debt items per sprint (should be low)

• Time to resolve (should decrease)

Business Metrics:

• Bug rate (should decrease)

• Feature delivery speed (should increase)

• Developer satisfaction (should increase)