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

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