## Tech Debt

Quantitatively analyzes technical debt in projects, visualizes health scores and impact on development efficiency. Tracks improvement status through trend analysis and creates prioritized improvement plans with calculated time costs.

### Usage

```bash
# Analyze project structure for technical debt
ls -la
"Analyze technical debt in this project and create improvement plan"
```

### Project Health Dashboard

```text
Project Health Score: 72/100
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Category-wise Scores
├─ Dependency freshness: ████████░░ 82% (Up-to-date: 45/55)
├─ Documentation completeness: ███░░░░░░░ 35% (Missing README, API docs)
├─ Test coverage: ██████░░░░ 65% (Target: 80%)
├─ Security: ███████░░░ 78% (Vulnerabilities: 2 Medium)
├─ Architecture: ██████░░░░ 60% (Circular dependencies: 3 locations)
└─ Code quality: ███████░░░ 70% (High complexity: 12 files)

📈 Trends (Past 30 days)
├─ Overall score: 68 → 72 (+4) ↗️
├─ Improvements: 12 items ✅
├─ New debt: 3 items ⚠️
├─ Resolved debt: 8 items 🎉
└─ Improvement rate: +0.13/day

⏱️ Time Impact of Debt
├─ Development speed reduction: -20% (New features take 1.25x normal time)
├─ Bug fix time increase: +15% (Average fix time 2h → 2.3h)
├─ Code review overhead: +30% (Increased understanding time due to complexity)
├─ Onboarding delay: +50% (Time for new members to understand)
└─ Cumulative delay: 40 hours/week equivalent

🎯 Expected Benefits from Improvement (Time-based)
├─ Immediate effect: +10% development speed (After 1 week)
├─ Short-term effect: -25% bug rate (After 1 month)
├─ Medium-term effect: +30% development speed (After 3 months)
├─ Long-term effect: -50% maintenance time (After 6 months)
└─ ROI: Invest 40 hours → Recover 120 hours (3 months)
```

### Basic Examples

```bash
# Detailed health score analysis
find . -name "*.js" -o -name "*.ts" | xargs wc -l | sort -rn | head -10
"Calculate project health score and evaluate by category"

# TODO/FIXME debt impact analysis
grep -r "TODO\|FIXME\|HACK\|XXX\|WORKAROUND" . --exclude-dir=node_modules --exclude-dir=.git
"Evaluate these TODOs by debt impact (time × importance)"

# Dependency health check
ls -la | grep -E "package.json|Cargo.toml|pubspec.yaml|go.mod|requirements.txt"
"Calculate dependency freshness score and analyze update risks and benefits"
```

### Collaboration with Claude

```bash
# Comprehensive technical debt analysis
ls -la && find . -name "*.md" -maxdepth 2 -exec head -20 {} \;
"Analyze technical debt in this project from the following perspectives:
1. Code quality (complexity, duplication, maintainability)
2. Dependency health
3. Security risks
4. Performance issues
5. Test coverage gaps"

# Architecture debt analysis
find . -type d -name "src" -o -name "lib" -o -name "app" | head -10 | xargs ls -la
"Identify architecture-level technical debt and propose refactoring plan"

# Prioritized improvement plan
"Evaluate technical debt using the following criteria and present in table format:
- Impact level (High/Medium/Low)
- Fix cost (time)
- Technical risk (system failure, data loss potential)
- Time savings from improvement
- Recommended implementation timing"
```

### Detailed Examples

```bash
# Auto-detect project type and analyze
find . -maxdepth 2 -type f \( -name "package.json" -o -name "Cargo.toml" -o -name "pubspec.yaml" -o -name "go.mod" -o -name "pom.xml" \)
"Based on detected project type, analyze:
1. Language/framework-specific technical debt
2. Deviations from best practices
3. Modernization opportunities
4. Step-by-step improvement strategy"

# Code quality metrics analysis
find . -type f -name "*" | grep -E "\.(js|ts|py|rs|go|dart|kotlin|swift|java)$" | wc -l
"Analyze project code quality and present these metrics:
- Functions with high cyclomatic complexity
- Duplicate code detection
- Overly long files/functions
- Missing proper error handling"

# Security debt detection
grep -r "password\|secret\|key\|token" . --exclude-dir=.git --exclude-dir=node_modules | grep -v ".env.example"
"Detect security-related technical debt and propose fix priorities and countermeasures"

# Test coverage gap analysis
find . -type f \( -name "*test*" -o -name "*spec*" \) | wc -l && find . -type f -name "*.md" | xargs grep -l "test"
"Analyze technical debt in test coverage and propose testing strategy"
```

### Debt Priority Matrix

```text
Priority = (Impact × Frequency) ÷ Fix Cost
```

| Priority                 | Development Impact | Fix Cost | Time Savings | Investment Efficiency | Response Deadline |
| ------------------------ | ------------------ | -------- | ------------ | --------------------- | ----------------- |
| **[P0] Fix Immediately** | High               | Low      | > 5x         | Invest 1h → Save 5h+  | Immediately       |
| **[P1] This Week**       | High               | Medium   | 2-5x         | Invest 1h → Save 2-5h | Within 1 week     |
| **[P2] This Month**      | Low                | High     | 1-2x         | Invest 1h → Save 1-2h | Within 1 month    |
| **[P3] This Quarter**    | Low                | Low      | < 1x         | Investment = Savings  | Within 3 months   |

### Debt Type Evaluation Criteria

| Debt Type              | Detection Method                      | Development Impact                                | Fix Time |
| ---------------------- | ------------------------------------- | ------------------------------------------------- | -------- |
| **Architecture Debt**  | Circular dependencies, tight coupling | Large impact scope on changes, testing difficulty | 40-80h   |
| **Security Debt**      | CVE scans, OWASP                      | Vulnerability risks, compliance issues            | 8-40h    |
| **Performance Debt**   | N+1 queries, memory leaks             | Increased response time, resource consumption     | 16-40h   |
| **Test Debt**          | Coverage < 60%                        | Delayed bug detection, unstable quality           | 20-60h   |
| **Documentation Debt** | Missing README, API docs              | Increased onboarding time                         | 8-24h    |
| **Dependency Debt**    | 2+ years without updates              | Security risks, compatibility issues              | 4-16h    |
| **Code Quality Debt**  | Complexity > 10                       | Increased understanding/modification time         | 2-8h     |

### Technical Debt Impact Calculation

```text
Impact = Σ(Weight of each factor × Measured value)

📊 Measurable Impact Indicators:
├─ Development Speed Impact
│  ├─ Code understanding time: +X% (proportional to complexity)
│  ├─ Change impact scope: Y files (measured by coupling)
│  └─ Test execution time: Z minutes (CI/CD pipeline)
│
├─ Quality Impact
│  ├─ Bug occurrence rate: +25% per complexity score of 10
│  ├─ Review time: Lines of code × Complexity coefficient
│  └─ Test gap risk: High risk when coverage < 60%
│
└─ Team Efficiency Impact
   ├─ Onboarding time: +100% when documentation lacking
   ├─ Knowledge silos: Caution when single contributor rate >80%
   └─ Code duplication fix locations: Duplication rate × Change frequency
```

### Time-based ROI Calculation

```text
ROI = (Time Saved - Investment Time) ÷ Investment Time × 100

Example: Resolving circular dependencies
├─ Investment time: 16 hours (refactoring)
├─ Monthly savings:
│  ├─ Compilation time: -10 min/day × 20 days = 200 min
│  ├─ Debug time: -2 hours/week × 4 weeks = 8 hours
│  └─ New feature development: -30% time reduction = 12 hours
├─ Monthly time savings: 23.3 hours
└─ 3-month ROI: (70 - 16) ÷ 16 × 100 = 337%
```

### Notes

- Automatically detects project language and framework for tailored analysis
- Health score evaluated on 0-100 scale: 70+ healthy, 50 or below needs improvement
- Calculates specific time costs and improvement benefits to support data-driven decision making
- For monetary conversion, specify team average hourly rate or project-specific coefficients separately