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)