tech-debt-analyzer

What this skill does

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