Initial commit

commands/tech-debt.md

@@ -0,0 +1,185 @@
+## 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