tech-debt-analyzer

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

```bash
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:

```bash
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:**
```markdown
## 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. **Rev