/tech-debt

description: 'Quantitative tech debt analysis and improvement plan. Trigger with "analyze tech debt", "check project health", "evaluate code debt", "create improvement plan", "debt score?".'
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash

Quantitative tech debt analysis and improvement plan

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

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

Project Health Dashboard

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

# 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

# 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

# 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

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+