technical-debt-analyzer

Technical Debt Analyzer

Systematically identify, categorize, and prioritize technical debt across codebases. Provides actionable insights into code quality, architectural issues, and maintenance risks.

Core Capabilities

1. Code Quality Analysis

Identify code-level technical debt:

• Code smells - Long methods, large classes, duplicated code
• Complexity metrics - Cyclomatic complexity, nesting depth
• Naming issues - Poor variable/function names, inconsistent conventions
• Dead code - Unused functions, unreachable code, commented code
• Magic numbers - Hard-coded values without explanation
• Anti-patterns - Common design mistakes and bad practices

2. Architectural Debt

Detect structural and design issues:

• Tight coupling - Excessive dependencies between modules
• Missing abstractions - Duplicated logic that should be extracted
• Layer violations - Breaking architectural boundaries
• God objects - Classes/modules with too many responsibilities
• Circular dependencies - Modules depending on each other
• Inconsistent patterns - Mixed architectural styles

3. Maintenance Risk Assessment

Identify high-maintenance areas:

• Change frequency - Files modified frequently (hotspots)
• Bug density - Areas with recurring bugs
• Test coverage gaps - Critical code without tests
• Complexity + change - Complex code that changes often (highest risk)
• Knowledge concentration - Code only one person understands
• Outdated dependencies - Old libraries with security issues

4. Documentation Debt

Find documentation gaps:

• Missing documentation - Undocumented public APIs
• Outdated comments - Comments contradicting code
• Poor commit messages - Unclear change history
• Incomplete README - Setup/usage not documented
• Missing architecture docs - No design documentation

5. Test Debt

Assess test quality issues:

• Low coverage - Critical paths untested
• Flaky tests - Tests that fail intermittently
• Slow tests - Tests that slow down CI/CD
• Test duplication - Redundant test logic
• Missing test types - No integration/E2E tests
• Brittle tests - Tests that break with minor changes

Technical Debt Analysis Workflow

Step 1: Scan the Codebase

Gather evidence of technical debt:

Examine file structure:

# Look for:
- Large files (>500 lines)
- Deep nesting (>5 levels)
- Many files in single directory
- Inconsistent naming patterns

Analyze code metrics:

• Lines of code per file/function
• Cyclomatic complexity
• Code duplication percentage
• Dependency count
• Test coverage percentage

Review version control:

# Find frequently changed files (hotspots)
git log --format=format: --name-only | grep -v '^$' | sort | uniq -c | sort -rn | head -20

# Find files with many authors (knowledge spread)
git log --format='%an' --name-only | grep -v '^$' | sort | uniq -c

# Find large commits (risky changes)
git log --all --numstat --format="%H" | awk '

Step 2: Categorize Technical Debt

Classify findings into debt categories:

Code-level debt:

# Example: Long method
def process_order(order):  # 150 lines!
    # Validation
    # Price calculation
    # Inventory check
    # Payment processing
    # Email notification
    # Logging
    # Analytics
    # ...

# Debt: Violates Single Responsibility Principle
# Impact: Hard to test, modify, understand
# Priority: Medium

Architectural debt:

# Example: Tight coupling
from payment_processor import PaymentProcessor
from email_service import EmailService
from analytics import Analytics

class OrderService:
    def __init__(self):
        self.payment = PaymentProcessor()  # Direct dependency
        self.email = EmailService()        # Direct dependency
        self.analytics = Analytics()        # Direct dependency

# Debt: No dependency injection, hard to test
# Impact: Cannot mock dependencies, tightly coupled
# Priority: High

Test debt:

# Example: No tests for critical function
def calculate_refund(order, reason):
    # Complex refund logic...
    # No tests exist!

# Debt: Critical business logic untested
# Impact: High risk of bugs in refunds
# Priority: Critical

Step 3: Assess Impact and Priority

Rank technical debt by impact:

Priority scoring factors:

1. Business criticality - How important is this code?
2. Change frequency - How often does it change?
3. Current quality - How bad is it?
4. Risk level - What could go wrong?
5. Effort to fix - How hard to improve?

Priority matrix:

High Impact + Low Effort = Critical (fix first)
High Impact + High Effort = Important (plan carefully)
Low Impact + Low Effort = Nice-to-have (quick wins)
Low Impact + High Effort = Defer (don't bother)

Example scoring:

Technical Debt: Missing error handling in payment processing
- Business criticality: 10/10 (payments are critical)
- Change frequency: 8/10 (changes often)
- Current quality: 3/10 (poor)
- Risk level: 10/10 (could lose money)
- Effort to fix: 4/10 (moderate)

Overall Priority: CRITICAL
Recommended action: Fix immediately

Step 4: Generate Recommendations

Provide specific, actionable fixes:

Format:

## Technical Debt Item: [Name]

**Category:** [Code Quality/Architecture/Test/Documentation]
**Location:** [file:line or component]
**Severity:** [Critical/High/Medium/Low]
**Effort:** [Hours or Days estimate]

### Problem
[Clear description of the issue]

### Impact
[Why this matters - business/technical impact]

### Recommendation
[Specific steps to fix]

### Example Fix
[Code example if applicable]

### Benefits
[What improves after fixing]

Example:

## Technical Debt Item: God Class in OrderService

**Category:** Architectural Debt
**Location:** src/services/OrderService.java
**Severity:** High
**Effort:** 2-3 days

### Problem
OrderService class has 1,200 lines and handles 15 different responsibilities:
validation, pricing, inventory, payment, shipping, notifications, analytics,
logging, caching, etc.

### Impact
- Hard to test (requires mocking 15 dependencies)
- Changes risky (touches many concerns)
- Team bottleneck (everyone modifies this file)
- Poor reusability (can't use parts independently)

### Recommendation
1. Extract responsibilities into separate services:
   - ValidationService
   - PricingService
   - InventoryService
   - PaymentService
   - NotificationService

2. Use dependency injection for loose coupling

3. Introduce OrderOrchestrator to coordinate services

### Example Fix

// Before: God class class OrderService { void processOrder() { validate(); calculatePrice(); checkInventory(); processPayment(); sendEmail(); logAnalytics(); // ... } }

// After: Separated concerns class OrderOrchestrator { private ValidationService validator; private PricingService pricer; private PaymentService payment;

OrderOrchestrator(ValidationService v, PricingService p, PaymentService pm) { this.validator = v; this.pricer = p; this.payment = pm; }

void processOrder(Order order) { validator.validate(order); Price price = pricer.calculate(order); payment.process(order, price); } }

### Benefits
- Each service independently testable
- Clear separation of concerns
- Easier to maintain and extend
- Better code reuse
- Parallel development possible

Step 5: Create Action Plan

Prioritize and sequence fixes:

Suggested format:

## Technical Debt Remediation Plan

### Immediate Actions (This Sprint)
1. [Critical item 1] - [effort estimate]
2. [Critical item 2] - [effort estimate]

### Short Term (Next 1-2 Months)
1. [High priority item 1]
2. [High priority item 2]

### Long Term (3-6 Months)
1. [Strategic improvements]
2. [Architectural changes]

### Qu