tools-only 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:
- Business criticality - How important is this code?
- Change frequency - How often does it change?
- Current quality - How bad is it?
- Risk level - What could go wrong?
- 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
```java
// 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)
- [Critical item 1] - [effort estimate]
- [Critical item 2] - [effort estimate]
Short Term (Next 1-2 Months)
- [High priority item 1]
- [High priority item 2]
Long Term (3-6 Months)
- [Strategic improvements]
- [Architectural changes]
Quick Wins (Can do anytime)
- [Low effort improvements]
Monitoring
- Track technical debt metrics monthly
- Review hotspots after each release
- Code review checklist to prevent new debt
## Technical Debt Patterns
### Pattern 1: Code Smell - Long Method
**Detection:**
```python
# File: order_processor.py
def process_order(order_id): # 250 lines long!
# Get order from database
order = db.query(f"SELECT * FROM orders WHERE id = {order_id}")
# Validate customer
if not order.customer_id:
raise ValueError("No customer")
customer = db.query(f"SELECT * FROM customers WHERE id = {order.customer_id}")
# Check inventory for each item
for item in order.items:
inventory = db.query(f"SELECT * FROM inventory WHERE sku = {item.sku}")
if inventory.quantity < item.quantity:
# Send email to supplier
# Log shortage
# Update backorder
# ...
# Calculate pricing with discounts
# Process payment
# Update inventory
# Send confirmation email
# Update analytics
# ... (200+ more lines)
Analysis:
Category: Code Quality Debt
Severity: Medium
Issues:
- 250 lines in single function
- Multiple responsibilities (SRP violation)
- High cyclomatic complexity (15+)
- Hard to test
- SQL injection vulnerability
- Poor error handling
Recommendation:
# Extract into smaller, focused functions
def process_order(order_id):
"""Main orchestration - now only 20 lines."""
order = get_order(order_id)
validate_order(order)
check_inventory(order)
price = calculate_total(order)
process_payment(order, price)
fulfill_order(order)
send_confirmation(order)
return order
def get_order(order_id):
"""Single responsibility: fetch order."""
return Order.query.get(order_id)
def validate_order(order):
"""Single responsibility: validation."""
if not order.customer_id:
raise ValidationError("Order has no customer")
if not order.items:
raise ValidationError("Order has no items")
def check_inventory(order):
"""Single responsibility: inventory check."""
for item in order.items:
inventory = Inventory.query.filter_by(sku=item.sku).first()
if inventory.quantity < item.quantity:
handle_shortage(item, inventory)
Benefits:
- Each function testable in isolation
- Clear single responsibility
- Easier to understand and modify
- Better error handling
- Reusable components
Pattern 2: Architectural Debt - Circular Dependency
Detection:
# services/order_service.py
from services.customer_service import CustomerService
class OrderService:
def get_customer_orders(self, customer_id):
customer = CustomerService().get_customer(customer_id)
return self.filter_by_customer(customer)
# services/customer_service.py
from services.order_service import OrderService
class CustomerService:
def get_customer_with_orders(self, customer_id):
orders = OrderService().get_orders_by_customer(customer_id)
customer = self.get_customer(customer_id)
customer.orders = orders
return customer
Analysis:
Category: Architectural Debt
Severity: High
Issues:
- Circular dependency (OrderService ↔ CustomerService)
- Import errors possible
- Hard to test in isolation
- Tight coupling
- Poor separation of concerns
Recommendation:
# Option 1: Introduce repository pattern
# repositories/order_repository.py
class OrderRepository:
def get_by_customer(self, customer_id):
return Order.query.filter_by(customer_id=customer_id).all()
# services/customer_service.py
from repositories.order_repository import OrderRepository
class CustomerService:
def __init__(self, order_repo):
self.order_repo = order_repo
def get_customer_with_orders(self, customer_id):
customer = self.get_customer(customer_id)
customer.orders = self.order_repo.get_by_customer(customer_id)
return customer
# Option 2: Use dependency injection
# Break the cycle by injecting dependencies
class CustomerService:
def __init__(self, order_service=None):
self.order_service = order_service
def get_customer_with_orders(self, customer_id):
if self.order_service:
orders = self.order_service.get_orders(customer_id)
else:
orders = []
# ...
Benefits:
- No circular dependencies
- Services testable independently
- Clear dependency direction
- Easier to understand flow
Pattern 3: Test Debt - Missing Critical Tests
Detection:
# payment_processor.py - NO TESTS!
def process_refund(order, amount, reason):
"""Process refund to customer's payment method."""
if amount > order.total:
# What happens here? Not tested!
pass
payment_method = get_payment_method(order.payment_id)
if payment_method.type == "credit_card":
result = refund_to_card(payment_method, amount)
elif payment_method.type == "paypal":
result = refund_to_paypal(payment_method, amount)
else:
# Edge case - not tested!
result = manual_refund_process(payment_method, amount)
# What if refund fails? Not tested!
return result
Analysis:
Category: Test Debt
Severity: Critical
Issues:
- No tests for critical payment function
- Multiple edge cases untested
- Error handling not verified
- Business logic unvalidated
- High risk of bugs
Coverage: 0%
Recommendation:
# Add comprehensive test suite
def test_process_refund_success():
"""Test successful refund."""
order = create_test_order(total=100)
result = process_refund(order, 50, "Customer request")
assert result.success is True
assert result.amount == 50
def test_process_refund_exceeds_total():
"""Test that refund cannot exceed order total."""
order = create_test_order(total=100)
with pytest.raises(ValueError, match="exceeds order total"):
process_refund(order, 150, "Invalid amount")
def test_process_refund_credit_card():
"""Test refund to credit card."""
order = create_test_order(payment_type="credit_card")
result = process_refund(order, 50, "Test")
assert result.method == "credit_card"
def test_process_refund_paypal():
"""Test refund to PayPal."""
order = create_test_order(payment_type="paypal")
result = process_refund(order, 50, "Test")
assert result.method == "paypal"
def test_process_refund_unknown_payment_type():
"""Test handling of unknown payment type."""
order = create_test_order(payment_type="bitcoin")
result = process_refund(order, 50, "Test")
assert result.requires_manual_processing is True
def test_process_refund_payment_failure():
"""Test handling of payment gateway failure."""
order = create_test_order()
with patch('payment_gateway.refund') as mock:
mock.side_effect = PaymentGatewayError("Network error")
with pytest.raises(RefundFailedError):
process_refund(order, 50, "Test")
Benefits:
- Critical payment logic validated
- Edge cases covered
- Error handling verified
- Safer to modify/refactor
- Documentation through tests
Pattern 4: Dependency Debt - Outdated Libraries
Detection:
// package.json
{
"dependencies": {
"express": "3.21.2", // Latest: 4.18.2 (security issues in 3.x)
"lodash": "4.17.20", // Latest: 4.17.21 (CVE-2020-8203)
"moment": "2.24.0", // Latest: 2.29.4 (deprecated, use day.js)
"request": "2.88.0" // Deprecated! Use axios or node-fetch
}
}
Analysis:
Category: Maintenance Risk
Severity: High
Issues:
- 3 packages with known security vulnerabilities
- 1 deprecated package still in use
- Missing critical security patches
- Outdated major versions
- Technical debt accumulating
Recommendation:
// Updated package.json
{
"dependencies": {
"express": "^4.18.2", // Updated to latest
"lodash": "^4.17.21", // Security patch applied
"dayjs": "^1.11.7", // Replaced moment (lighter, maintained)
"axios": "^1.3.0" // Replaced deprecated request
}
}
// Migration notes:
// 1. express 3→4: Update middleware syntax
// 2. moment→dayjs: Update date formatting calls
// 3. request→axios: Update HTTP client calls
// 4. lodash: No breaking changes, just update
// Estimated effort: 1-2 days
// Risk: Medium (requires testing)
// Priority: High (security vulnerabilities)
Migration example:
// Before (deprecated request)
const request = require('request');
request('https://api.example.com', (error, response, body) => {
console.log(body);
});
// After (axios)
const axios = require('axios');
const response = await axios.get('https://api.example.com');
console.log(response.data);
Benefits:
- Security vulnerabilities patched
- Access to new features
- Better performance (dayjs vs moment)
- Continued maintenance support
Pattern 5: Documentation Debt - Undocumented API
Detection:
# api/user_controller.py - No documentation!
@app.route('/api/users/<id>/settings', methods=['PUT'])
def update_user_settings(id):
# What fields are accepted? Unknown!
# What's the response format? Unknown!
# What errors can occur? Unknown!
data = request.json
user = User.query.get(id)
user.settings = data
db.session.commit()
return jsonify(user.to_dict())
Analysis:
Category: Documentation Debt
Severity: Medium
Issues:
- No API documentation
- Request/response format unclear
- Validation rules unknown
- Error handling undocumented
- Hard for other developers to use
Recommendation:
@app.route('/api/users/<id>/settings', methods=['PUT'])
def update_user_settings(id):
"""
Update user settings.
Args:
id (str): User ID
Request Body:
{
"theme": "dark" | "light",
"notifications": boolean,
"language": str (ISO 639-1 code)
}
Returns:
200 OK:
{
"id": str,
"settings": {
"theme": str,
"notifications": bool,
"language": str
}
}
404 Not Found:
{"error": "User not found"}
400 Bad Request:
{"error": "Invalid theme value"}
Example:
PUT /api/users/123/settings
{
"theme": "dark",
"notifications": true,
"language": "en"
}
"""
try:
data = request.json
validate_settings(data) # Validate input
user = User.query.get_or_404(id)
user.update_settings(data)
db.session.commit()
return jsonify({
"id": user.id,
"settings": user.settings
}), 200
except ValidationError as e:
return jsonify({"error": str(e)}), 400
Benefits:
- Clear API contract
- Easier for developers to use
- Self-documenting code
- Reduces support questions
Pattern 6: Duplication Debt - Copy-Pasted Code
Detection:
# analytics.py
def track_signup(user):
event = {
"type": "signup",
"user_id": user.id,
"timestamp": datetime.now(),
"properties": {"email": user.email}
}
analytics_client.track(event)
logger.info(f"Tracked signup: {user.id}")
# payments.py
def track_purchase(order):
event = {
"type": "purchase",
"user_id": order.user_id,
"timestamp": datetime.now(),
"properties": {"amount": order.total}
}
analytics_client.track(event)
logger.info(f"Tracked purchase: {order.id}")
# notifications.py
def track_notification(user, notification):
event = {
"type": "notification",
"user_id": user.id,
"timestamp": datetime.now(),
"properties": {"message": notification.text}
}
analytics_client.track(event)
logger.info(f"Tracked notification: {user.id}")
Analysis:
Category: Code Quality Debt
Severity: Medium
Issues:
- Same pattern duplicated 3+ times
- Violates DRY principle
- Hard to modify (must update all copies)
- Inconsistent implementations possible
- Maintenance burden
Recommendation:
# Extract common pattern into reusable function
def track_event(event_type, user_id, properties=None):
"""
Track analytics event.
Args:
event_type: Type of event (signup, purchase, etc.)
user_id: User ID associated with event
properties: Optional dict of event properties
"""
event = {
"type": event_type,
"user_id": user_id,
"timestamp": datetime.now(),
"properties": properties or {}
}
analytics_client.track(event)
logger.info(f"Tracked {event_type}: {user_id}")
# Now use the extracted function
def track_signup(user):
track_event("signup", user.id, {"email": user.email})
def track_purchase(order):
track_event("purchase", order.user_id, {"amount": order.total})
def track_notification(user, notification):
track_event("notification", user.id, {"message": notification.text})
Benefits:
- Single source of truth
- Easier to maintain
- Consistent behavior
- Less code overall
- Easier to add features (e.g., add filtering to track_event)
Code Quality Metrics
Cyclomatic Complexity
Measure of code complexity based on decision points:
Complexity = edges - nodes + 2 * connected_components
Guidelines:
- 1-10: Simple, low risk
- 11-20: Moderate, medium risk
- 21-50: Complex, high risk
- 50+: Very complex, very high risk (refactor!)
Example:
def calculate_discount(customer, order): # Complexity: 8
if customer.is_premium: # +1
if order.total > 1000: # +1
return 0.2
else: # +1
return 0.15
elif customer.is_member: # +1
if order.total > 500: # +1
return 0.1
else: # +1
return 0.05
else: # +1
return 0
Maintainability Index
Combined metric for maintainability:
MI = max(0, (171 - 5.2 * ln(HV) - 0.23 * CC - 16.2 * ln(LOC)) * 100 / 171)
Where:
- HV = Halstead Volume
- CC = Cyclomatic Complexity
- LOC = Lines of Code
Guidelines:
- 85-100: Highly maintainable
- 65-85: Moderately maintainable
- 0-65: Hard to maintain (technical debt!)
Code Churn
Measure of code volatility:
# Files with highest churn (lines changed)
git log --all --numstat --format="%H" --since="3 months ago" | \
awk '{if ($1 != "") files[$3] += $1 + $2} END {for (f in files) print files[f], f}' | \
sort -rn | head -20
High churn + high complexity = Highest maintenance risk
Technical Debt Report Template
# Technical Debt Analysis Report
**Project:** [Project Name]
**Date:** [Analysis Date]
**Analyzed By:** [Name/Tool]
## Executive Summary
**Overall Debt Level:** [High/Medium/Low]
**Total Items:** [Count]
**Critical Items:** [Count]
**Estimated Effort:** [Days/Weeks]
### Key Findings
1. [Most critical issue]
2. [Second critical issue]
3. [Third critical issue]
### Recommendations
1. [Top priority action]
2. [Second priority action]
3. [Third priority action]
## Debt Inventory
### Critical Priority (Fix Immediately)
#### 1. [Debt Item Name]
- **Category:** [Code Quality/Architecture/Test/etc.]
- **Location:** [file:line or component]
- **Impact:** [Description of business/technical impact]
- **Effort:** [Estimate]
- **Recommendation:** [Specific fix]
#### 2. [Next critical item...]
### High Priority (Next Sprint)
[Same format as critical]
### Medium Priority (Next 1-2 Months)
[Same format]
### Low Priority (Nice-to-Have)
[Same format]
## Metrics Summary
| Metric | Current | Target | Status |
|--------|---------|--------|--------|
| Test Coverage | 65% | 80% | ⚠️ Below target |
| Cyclomatic Complexity (avg) | 15 | <10 | ⚠️ Too high |
| Code Duplication | 12% | <5% | ⚠️ Too high |
| Outdated Dependencies | 8 | 0 | ⚠️ Action needed |
| Documentation Coverage | 40% | 80% | ⚠️ Insufficient |
## Hotspot Analysis
### Top 10 Maintenance Hotspots
(High complexity + High change frequency)
1. **src/services/OrderService.java** - Complexity: 45, Changes: 87
2. **src/controllers/UserController.py** - Complexity: 38, Changes: 62
3. [Continue...]
## Action Plan
### Phase 1: Immediate (This Sprint)
- [ ] Fix critical security vulnerability in payment processing
- [ ] Add tests for refund logic
- [ ] Update vulnerable dependencies
**Estimated Effort:** 3-5 days
### Phase 2: Short Term (Next 1-2 Months)
- [ ] Refactor OrderService god class
- [ ] Eliminate circular dependencies
- [ ] Improve test coverage to 80%
**Estimated Effort:** 2-3 weeks
### Phase 3: Long Term (3-6 Months)
- [ ] Architectural improvements
- [ ] Documentation overhaul
- [ ] Performance optimization
**Estimated Effort:** 1-2 months
## Appendix
### Tools Used
- [Static analysis tools]
- [Coverage tools]
- [Complexity analyzers]
### Analysis Scope
- [Directories analyzed]
- [Exclusions]
- [Time period for git analysis]
Best Practices
- Regular analysis - Run technical debt analysis quarterly or before major releases
- Automate detection - Use static analysis tools in CI/CD pipeline
- Track metrics - Monitor trends over time, not just point-in-time snapshots
- Prioritize ruthlessly - Focus on high-impact, high-risk debt first
- Budget time - Allocate 10-20% of each sprint to debt reduction
- Prevent new debt - Code review checklist, quality gates, linting
- Measure progress - Track debt reduction metrics over time
- Communicate impact - Translate technical debt to business risk
- Balance with features - Don't stop all feature work, but don't ignore debt
- Make it visible - Dashboard showing debt trends, hotspots, and priorities
Common Anti-Patterns
Anti-Pattern 1: The "Rewrite" Trap
Problem: "This code is terrible, let's rewrite it from scratch!"
Why it fails:
- Underestimates effort (Netscape effect)
- Loses institutional knowledge
- Introduces new bugs
- Takes longer than incremental improvement
Better approach:
- Incremental refactoring
- Strangler fig pattern
- Add tests first, then refactor
- Preserve working functionality
Anti-Pattern 2: Perfection Paralysis
Problem: "We can't ship until we fix all technical debt!"
Why it fails:
- Infinite task (debt never goes to zero)
- Delays value delivery
- Business loses patience
- Team burnout
Better approach:
- Fix critical debt, ship with minor debt
- Continuous improvement
- Pragmatic prioritization
Anti-Pattern 3: Ignore and Hope
Problem: "We'll fix it later when we have time."
Why it fails:
- Later never comes
- Debt compounds (gets worse over time)
- Eventually forces painful emergency fixes
- Team morale suffers
Better approach:
- Schedule debt reduction in every sprint
- Boy Scout rule (leave code better than found)
- Track debt trend (going up or down?)