tech-debt-analyzer

SKILL.md

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)