tech-debt-analyzer

name	tech-debt-analyzer
description	This skill should be used when analyzing technical debt in a codebase, documenting code quality issues, creating technical debt registers, or assessing code maintainability. Use this for identifying code smells, architectural issues, dependency problems, missing documentation, security vulnerabilities, and creating comprehensive technical debt documentation. Use when this capability is needed.
metadata	{"author":"ailabs-393"}

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

1. Run analysis regularly (weekly or bi-weekly)
2. Combine automated + manual review for comprehensive coverage
3. Focus on high-churn areas first for maximum impact
4. Involve the team in debt identification
5. Be objective - all codebases have debt

Documentation Best Practices

1. Be specific - include file names, line numbers, examples
2. Explain impact - why does this matter?
3. Propose solutions - don't just complain, suggest fixes
4. Estimate effort - helps with prioritization
5. Track trends - is debt increasing or decreasing?

Remediation Best Practices

1. Fix critical items immediately - especially security
2. Allocate consistent time - 20% of sprint capacity
3. Celebrate wins - track and recognize debt reduction
4. Don't let perfect be the enemy of good - incremental improvement
5. Prevent new debt - easier than fixing old debt

Communication Best Practices

1. Make debt visible - share metrics with stakeholders
2. Educate on impact - connect debt to business outcomes
3. Get buy-in - explain ROI of debt reduction
4. Regular updates - include in sprint reviews
5. 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