Technical Debt Management Strategies: A Comprehensive Guide

Debt Type: Intentional/Strategic
Examples:
  - Launching MVP with limited features
  - Using simplified architecture for faster time-to-market
  - Choosing proven tech over cutting-edge solutions
Risk Level: Low (when documented and tracked)
Repayment: Planned refactoring after market validation

Debt Type: Unintentional/Reckless
Examples:
  - No code review process
  - Missing test coverage
  - Ignoring best practices
  - Copy-paste programming
Risk Level: High
Repayment: Immediate prioritization

Debt Type: Legacy/Historical
Examples:
  - Outdated frameworks (AngularJS, Rails 4)
  - Deprecated APIs
  - Old programming languages
  - Monolithic architectures
Risk Level: Medium to High
Repayment: Strangler Fig pattern, incremental migration

Debt Type: Infrastructure/Environmental
Examples:
  - Missing CI/CD pipelines
  - Manual deployment processes
  - Poor monitoring and logging
  - Inadequate documentation
Risk Level: Medium
Repayment: Infrastructure as Code, automation

# Example: Simple complexity checker
import ast
import os

class CodeComplexityAnalyzer:
    """Analyze code complexity metrics."""
    
    def __init__(self, repo_path):
        self.repo_path = repo_path
        self.issues = []
    
    def analyze_file(self, filepath):
        """Analyze a single file for complexity issues."""
        with open(filepath, 'r') as f:
            tree = ast.parse(f.read())
        
        issues = {
            'cyclomatic_complexity': 0,
            'function_count': 0,
            'deep_nesting': 0,
            'lines_of_code': 0,
            'duplicate_code': False
        }
        
        for node in ast.walk(tree):
            if isinstance(node, ast.FunctionDef):
                issues['function_count'] += 1
                issues['cyclomatic_complexity'] += self._calculate_complexity(node)
                issues['deep_nesting'] = max(
                    issues['deep_nesting'],
                    self._get_nesting_depth(node)
                )
        
        return issues
    
    def _calculate_complexity(self, node):
        """Calculate cyclomatic complexity."""
        complexity = 1
        for child in ast.walk(node):
            if isinstance(child, (ast.If, ast.While, ast.For, 
                                   ast.ExceptHandler)):
                complexity += 1
            elif isinstance(child, ast.BoolOp):
                complexity += len(child.values) - 1
        return complexity
    
    def _get_nesting_depth(self, node, current_depth=0):
        """Get maximum nesting depth."""
        max_depth = current_depth
        for child in ast.iter_child_nodes(node):
            if isinstance(child, (ast.If, ast.While, ast.For, 
                                   ast.With)):
                max_depth = max(
                    max_depth,
                    self._get_nesting_depth(child, current_depth + 1)
                )
        return max_depth
    
    def scan_repository(self):
        """Scan entire repository."""
        for root, dirs, files in os.walk(self.repo_path):
            dirs[:] = [d for d in dirs if not d.startswith('.')]
            for file in files:
                if file.endswith('.py'):
                    filepath = os.path.join(root, file)
                    issues = self.analyze_file(filepath)
                    
                    if issues['cyclomatic_complexity'] > 10:
                        self.issues.append({
                            'file': filepath,
                            'type': 'high_complexity',
                            'value': issues['cyclomatic_complexity']
                        })
                    
                    if issues['deep_nesting'] > 4:
                        self.issues.append({
                            'file': filepath,
                            'type': 'deep_nesting',
                            'value': issues['deep_nesting']
                        })
        
        return self.issues

# Usage
analyzer = CodeComplexityAnalyzer('./src')
debt_issues = analyzer.scan_repository()
for issue in debt_issues:
    print(f"{issue['type']}: {issue['file']} - {issue['value']}")

| Category | Smell | Indicator | Severity |
|----------|-------|-----------|----------|
| Bloaters | Long Method | > 10 lines | Medium |
| Bloaters | Large Class | > 500 lines | Medium |
| Bloaters | Primitive Obsession | Many primitives | Low |
| Bloaters | Long Parameter List | > 4 parameters | Low |
| Object Abusers | Switch Statements | Multiple switches | Medium |
| Object Abusers | Temporary Field | Unused fields | Medium |
| Change Preventers | Divergent Change | One change affects many | High |
| Change Preventers | Shotgun Surgery | Many changes for one fix | High |
| Change Preventers | Parallel Inheritance | Similar hierarchies | Medium |
| Encapsulation | Feature Envy | Uses more of other class | Low |
| Encapsulation | Data Clumps | Same parameters together | Low |
| Encapsulation | Primitive Obsession | No small objects | Low |
| Coupling | Message Chains | A→B→C→D calls | Medium |
| Coupling | Middle Man | Delegates everything | Low |
| Coupling | Inappropriate Intimacy | Knows too much | Medium |
| Other | Alternative Classes | Same functionality | Medium |
| Other | Incomplete Library | Can't modify | High |
| Other | Data Class | No behavior | Low |
| Other | Refused Bequest | Ignores parent | Low |
| Other | Comments | Explains bad code | Low |

# Using pytest-cov for Python
pip install pytest pytest-cov

# Run with coverage
pytest --cov=src --cov-report=html --cov-report=term

# Minimum coverage thresholds in pytest.ini
# [pytest]
# min_coverage = 80
# fail_under = 80

// Using Jest with coverage for JavaScript/TypeScript
// package.json
{
  "jest": {
    "coverageThreshold": {
      "global": {
        "branches": 80,
        "functions": 80,
        "lines": 80,
        "statements": 80
      },
      "./src/services/": {
        "branches": 90,
        "functions": 90,
        "lines": 90,
        "statements": 90
      }
    }
  }
}

# Example: Dependency analysis using import graphs
import ast
import os
from collections import defaultdict
from typing import Dict, Set

class DependencyAnalyzer:
    """Analyze code dependencies and coupling."""
    
    def __init__(self, source_dir: str):
        self.source_dir = source_dir
        self.dependencies: Dict[str, Set[str]] = defaultdict(set)
        self.external_deps: Dict[str, Set[str]] = defaultdict(set)
    
    def analyze(self):
        """Analyze all Python files in the source directory."""
        for root, _, files in os.walk(self.source_dir):
            for file in files:
                if file.endswith('.py'):
                    filepath = os.path.join(root, file)
                    self._analyze_file(filepath)
    
    def _analyze_file(self, filepath: str):
        """Analyze imports in a single file."""
        module_name = self._get_module_name(filepath)
        
        try:
            with open(filepath, 'r') as f:
                tree = ast.parse(f.read())
        except:
            return
        
        for node in ast.walk(tree):
            if isinstance(node, ast.Import):
                for alias in node.names:
                    self._record_dependency(module_name, alias.name)
            
            if isinstance(node, ast.ImportFrom):
                if node.module:
                    self._record_dependency(module_name, node.module)
    
    def _get_module_name(self, filepath: str) -> str:
        """Convert filepath to module name."""
        rel_path = os.path.relpath(filepath, self.source_dir)
        return rel_path.replace('/', '.').replace('.py', '')
    
    def _record_dependency(self, from_module: str, to_module: str):
        """Record a dependency relationship."""
        if to_module.startswith('.'):
            return
        
        # Check if internal or external
        if to_module.startswith('src.') or to_module in ['django', 'flask', 'fastapi']:
            internal_modules = [
                m.replace('.py', '') 
                for m in os.listdir(self.source_dir)
                if m.endswith('.py')
            ]
            if any(to_module.startswith(m) for m in internal_modules):
                self.dependencies[from_module].add(to_module)
            else:
                self.external_deps[from_module].add(to_module)
        else:
            self.external_deps[from_module].add(to_module)
    
    def find_circular_dependencies(self) -> list:
        """Detect circular dependencies."""
        def has_cycle(module, visited, rec_stack):
            visited.add(module)
            rec_stack.add(module)
            
            for dep in self.dependencies.get(module, []):
                if dep not in visited:
                    if has_cycle(dep, visited, rec_stack):
                        return True
                elif dep in rec_stack:
                    return True
            
            rec_stack.remove(module)
            return False
        
        cycles = []
        for module in self.dependencies:
            visited = set()
            rec_stack = set()
            if has_cycle(module, visited, rec_stack):
                cycles.append(module)
        
        return cycles
    
    def get_metrics(self) -> dict:
        """Calculate coupling metrics."""
        metrics = {
            'total_internal_deps': sum(
                len(deps) for deps in self.dependencies.values()
            ),
            'total_external_deps': sum(
                len(deps) for deps in self.external_deps.values()
            ),
            'modules_with_no_deps': 0,
            'modules_depending_on_many': 0,
            'circular_dependencies': self.find_circular_dependencies()
        }
        
        for module, deps in self.dependencies.items():
            if len(deps) == 0:
                metrics['modules_with_no_deps'] += 1
            if len(deps) > 10:
                metrics['modules_depending_on_many'] += 1
        
        return metrics

# Usage
analyzer = DependencyAnalyzer('./src')
analyzer.analyze()
metrics = analyzer.get_metrics()

print(f"Internal dependencies: {metrics['total_internal_deps']}")
print(f"External dependencies: {metrics['total_external_deps']}")
print(f"Circular dependencies: {metrics['circular_dependencies']}")

# Example: .arcconfig or . Cz / rules.yaml
# Detect architecture violations
rules:
  - name: "Clean Architecture Compliance"
    description: "Domain layer must not depend on external frameworks"
    violation_patterns:
      - "domain/.*\\.py$ contains import (django|flask|sqlalchemy)"
      - "domain/.*\\.py$ contains from (django|flask|sqlalchemy)"
    
  - name: "Dependency Rule"
    description: "Dependencies must point inward"
    check: "Verify import direction in dependency graph"
    
  - name: "Interface Segregation"
    description: "No fat interfaces"
    rule: "Maximum 5 methods per interface"

## Technical Debt Categories

### High Priority (Fix Within Sprint)
- [ ] Security vulnerabilities
- [ ] Critical bugs affecting users
- [ ] Performance issues causing timeouts
- [ ] Data integrity risks

### Medium Priority (Fix Within Quarter)
- [ ] Code smells (duplication, complexity)
- [ ] Missing test coverage
- [ ] Inadequate error handling
- [ ] Poor documentation

### Low Priority (Backlog)
- [ ] Naming improvements
- [ ] Code formatting
- [ ] Minor refactoring
- [ ] Tool upgrades

# Example: Calculate development lead time
import subprocess
from datetime import datetime, timedelta
from typing import List, Dict

class LeadTimeAnalyzer:
    """Analyze development lead time from git history."""
    
    def __init__(self, repo_path: str):
        self.repo_path = repo_path
    
    def get_commit_lead_time(self, branch: str = "main") -> List[Dict]:
        """Calculate time from first commit to merge."""
        # Get merged PR commits
        result = subprocess.run(
            ["git", "log", "--merges", "--format=%H|%ai|%an", 
             f"--after={datetime.now() - timedelta(days=90)}"],
            cwd=self.repo_path,
            capture_output=True,
            text=True
        )
        
        lead_times = []
        for line in result.stdout.strip().split('\n'):
            if '|' in line:
                commit_hash, date_str, author = line.split('|')
                # Find first commit in the branch
                first_commit = self._find_first_commit(commit_hash)
                if first_commit:
                    lead_times.append({
                        'commit': commit_hash[:8],
                        'author': author,
                        'first_commit_date': first_commit,
                        'merge_date': date_str,
                        'lead_time_days': (
                            datetime.fromisoformat(date_str) - 
                            first_commit
                        ).days
                    })
        
        return lead_times
    
    def _find_first_commit(self, commit_hash: str) -> datetime:
        """Find the first commit in a merge."""
        result = subprocess.run(
            ["git", "log", "--format=%ai", 
             f"{commit_hash}^..{commit_hash}"],
            cwd=self.repo_path,
            capture_output=True,
            text=True
        )
        if result.stdout:
            return datetime.fromisoformat(result.stdout.strip().split('\n')[-1])
        return None
    
    def get_average_lead_time(self) -> float:
        """Get average lead time in days."""
        lead_times = self.get_commit_lead_time()
        if not lead_times:
            return 0
        
        total_days = sum(lt['lead_time_days'] for lt in lead_times)
        return total_days / len(lead_times)

# Usage
analyzer = LeadTimeAnalyzer('./')
avg_lead_time = analyzer.get_average_lead_time()
print(f"Average lead time: {avg_lead_time:.1f} days")

# Example: Debt cost estimation
from dataclasses import dataclass
from typing import List

@dataclass
class DebtItem:
    """Represents a technical debt item."""
    id: str
    description: str
    category: str
    estimated_hours: float
    severity: str  # critical, high, medium, low
    affected_components: List[str]
    risk_multiplier: float = 1.0
    
    @property
    def total_cost(self) -> float:
        """Calculate total cost with risk multiplier."""
        return self.estimated_hours * self.risk_multiplier

class DebtCostCalculator:
    """Calculate total technical debt cost."""
    
    # Risk multipliers based on severity and urgency
    RISK_MULTIPLIERS = {
        ('critical', 'now'): 3.0,
        ('critical', 'soon'): 2.0,
        ('critical', 'later'): 1.5,
        ('high', 'now'): 2.0,
        ('high', 'soon'): 1.5,
        ('high', 'later'): 1.2,
        ('medium', 'now'): 1.5,
        ('medium', 'soon'): 1.2,
        ('medium', 'later'): 1.0,
        ('low', 'now'): 1.2,
        ('low', 'soon'): 1.0,
        ('low', 'later'): 0.8,
    }
    
    def __init__(self):
        self.debt_items: List[DebtItem] = []
    
    def add_debt(self, debt: DebtItem):
        """Add a debt item to tracking."""
        self.debt_items.append(debt)
    
    def calculate_total_cost(self) -> dict:
        """Calculate total debt cost."""
        total = 0
        by_category = {}
        by_severity = {}
        
        for debt in self.debt_items:
            cost = debt.estimated_hours * debt.risk_multiplier
            total += cost
            
            by_category[debt.category] = by_category.get(
                debt.category, 0
            ) + cost
            
            by_severity[debt.severity] = by_severity.get(
                debt.severity, 0
            ) + cost
        
        return {
            'total_hours': total,
            'by_category': by_category,
            'by_severity': by_severity,
            'item_count': len(self.debt_items)
        }

# Example usage
calculator = DebtCostCalculator()

# Add debt items
calculator.add_debt(DebtItem(
    id="DEBT-001",
    description="Migrate from AngularJS to Angular",
    category="legacy_framework",
    estimated_hours=320,
    severity="high",
    affected_components=["frontend"],
    risk_multiplier=1.5
))

calculator.add_debt(DebtItem(
    id="DEBT-002",
    description="Add integration test coverage",
    category="testing",
    estimated_hours=80,
    severity="medium",
    affected_components=["api", "services"],
    risk_multiplier=1.2
))

result = calculator.calculate_total_cost()
print(f"Total debt cost: {result['total_hours']} hours")
print(f"By category: {result['by_category']}")

# Calculate the "interest" accrued on technical debt
# Based on development slow-down factors

class DebtInterestCalculator:
    """Calculate interest accrued on technical debt."""
    
    # Average slow-down factors per debt type
    SLOWDOWN_FACTORS = {
        'complex_code': 1.15,      # 15% slower
        'no_tests': 1.20,          # 20% slower
        'poor_documentation': 1.10,
        'tight_coupling': 1.25,   # 25% slower
        'duplication': 1.12,
        'naming_issues': 1.05,
        'global_state': 1.18,
        'magic_numbers': 1.08,
    }
    
    def __init__(self, hourly_rate: float = 100):
        self.hourly_rate = hourly_rate
    
    def calculate_interest(
        self, 
        debt_type: str, 
        development_hours: int,
        months_delayed: int
    ) -> dict:
        """Calculate interest accrued on debt."""
        factor = self.SLOWDOWN_FACTORS.get(debt_type, 1.0)
        
        # Interest = (Base hours × (factor - 1)) × months
        base_hours = development_hours
        extra_hours_per_month = base_hours * (factor - 1)
        total_extra_hours = extra_hours_per_month * months_delayed
        
        return {
            'debt_type': debt_type,
            'base_hours': base_hours,
            'slowdown_factor': factor,
            'months': months_delayed,
            'extra_hours': total_extra_hours,
            'cost_at_interest': total_extra_hours * self.hourly_rate,
            'effective_rate': f"{(factor - 1) * 100:.0f}% per month"
        }

# Usage
calculator = DebtInterestCalculator(hourly_rate=100)

# Calculate interest for different debt types
debts = [
    ('no_tests', 200, 6),
    ('complex_code', 150, 6),
    ('tight_coupling', 180, 6),
]

for debt_type, hours, months in debts:
    result = calculator.calculate_interest(
        debt_type, hours, months
    )
    print(f"{debt_type}: {result['extra_hours']:.0f} extra hours, "
          f"${result['cost_at_interest']:.0f}")

# Example: CI/CD pipeline with quality gates
# .github/workflows/quality-gates.yml

name: Quality Gates
on: [push, pull_request]

jobs:
  quality-gates:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install pylint flake8 bandit safety
          pip install pytest pytest-cov
      
      # Code Quality Gates
      - name: Run linters
        run: |
          pylint src --fail-under=8.0
          flake8 src --max-line-length=120
      
      # Security Gates
      - name: Security scan
        run: |
          bandit -r src
          safety check
      
      # Complexity Gates
      - name: Complexity check
        run: |
          # Fail if any function has complexity > 10
          pylint src --disable=all --enable=complexity \
            --max-complexity=10
      
      # Coverage Gates
      - name: Test with coverage
        run: |
          pytest --cov=src --cov-fail-under=80 \
            --cov-report=xml
      
      # Architecture Gates
      - name: Architecture validation
        run: |
          # Check dependency direction
          python scripts/check_architecture.py
      
      # Performance Gates (optional)
      - name: Performance baseline
        run: |
          pytest tests/performance/ --benchmark-json=benchmark.json
          # Compare against baseline

# Example: Pre-commit hooks for debt prevention
# .pre-commit-config.yaml

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files
  
  - repo: https://github.com/psf/black
    rev: 24.1.0
    hooks:
      - id: black
        language_version: python3.11
  
  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        args: ['--max-line-length=120', '--extend-ignore=E203']
  
  - repo: https://github.com/pycqa/isort
    rev: 5.13.0
    hooks:
      - id: isort
        args: ['--profile=black']
  
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.8.0
    hooks:
      - id: mypy
        args: ['--strict', '--ignore-missing-imports']
  
  - repo: https://github.com/bandit/bandit
    rev: 1.7.6
    hooks:
      - id: bandit
        args: ['-r', 'src/']

# Code Review Checklist for Debt Prevention

## Code Quality
- [ ] Code follows style guidelines
- [ ] No TODO comments without ticket reference
- [ ] No hardcoded values (use constants/config)
- [ ] No code duplication
- [ ] Functions are single-purpose (SRP)
- [ ] Meaningful variable and function names

## Testing
- [ ] Unit tests added for new functionality
- [ ] Tests are readable and maintainable
- [ ] Edge cases are covered
- [ ] No test logic in production code

## Security
- [ ] No secrets in code
- [ ] Input validation present
- [ ] Proper authentication/authorization
- [ ] SQL injection prevention
- [ ] XSS prevention

## Performance
- [ ] No N+1 queries
- [ ] Appropriate use of caching
- [ ] Lazy loading where appropriate
- [ ] Database indexes considered

## Documentation
- [ ] Complex logic is commented
- [ ] API endpoints documented
- [ ] README updated if needed
- [ ] Breaking changes documented

# Technical Debt Registry

## Template

| ID | Title | Description | Category | Severity | Effort (hrs) | Component | Created | Due Date | Status |
|----|-------|-------------|----------|----------|--------------|-----------|---------|----------|--------|

## Example Entries

| ID | Title | Description | Category | Severity | Effort | Component | Created | Due | Status |
|----|-------|-------------|----------|----------|--------|-----------|---------|-----|--------|
| TD-001 | Missing API Rate Limiting | No rate limiting on public API endpoints | Security | Critical | 16 | API | 2026-01-15 | 2026-02-01 | In Progress |
| TD-002 | Duplicated User Validation | Same validation logic in 3 places | Code Quality | Medium | 8 | Users | 2026-01-20 | 2026-03-01 | Backlog |
| TD-003 | Outdated Dependencies | Using deprecated libraries | Maintenance | Low | 24 | Utils | 2026-01-25 | 2026-Q2 | Backlog |
| TD-004 | Missing Error Logging | No structured error logging | Observability | High | 12 | Core | 2026-02-01 | 2026-02-15 | Planned |
| TD-005 | Tight Coupling in Payment Module | Payment service tightly coupled to orders | Architecture | High | 40 | Payments | 2026-01-10 | 2026-02-28 | In Progress |

# Example: Debt tracking dashboard data collector
import json
from datetime import datetime
from dataclasses import dataclass, asdict
from typing import List
import subprocess

@dataclass
class DebtMetrics:
    """Metrics about technical debt."""
    timestamp: str
    test_coverage: float
    code_complexity_avg: float
    lines_of_code: int
    duplicated_lines: int
    security_issues: int
    open_todos: int
    technical_debt_hours: float

class DebtMetricsCollector:
    """Collect technical debt metrics automatically."""
    
    def __init__(self, repo_path: str):
        self.repo_path = repo_path
    
    def collect(self) -> DebtMetrics:
        """Collect all metrics."""
        return DebtMetrics(
            timestamp=datetime.now().isoformat(),
            test_coverage=self._get_coverage(),
            complexity_avg=self._get_complexity(),
            loc=self._get_loc(),
            duplicated=self._get_duplication(),
            security_issues=self._get_security_issues(),
            todos=self._get_todos(),
            debt_hours=self._calculate_debt_hours()
        )
    
    def _get_coverage(self) -> float:
        """Get test coverage percentage."""
        # Parse coverage report
        try:
            result = subprocess.run(
                ['coverage', 'json', '-o', 'coverage.json'],
                cwd=self.repo_path,
                capture_output=True
            )
            with open(f'{self.repo_path}/coverage.json') as f:
                data = json.load(f)
            return data['totals']['percent_covered']
        except:
            return 0.0
    
    def _get_complexity(self) -> float:
        """Get average cyclomatic complexity."""
        # Use radon or similar tool
        return 5.0  # Placeholder
    
    def _get_loc(self) -> int:
        """Get lines of code."""
        # Use cloc or similar
        return 10000  # Placeholder
    
    def _get_duplication(self) -> int:
        """Get duplicated lines."""
        # Use pylint or similar
        return 500  # Placeholder
    
    def _get_security_issues(self) -> int:
        """Get security issues count."""
        # Use bandit
        return 3  # Placeholder
    
    def _get_todos(self) -> int:
        """Count TODO/FIXME comments."""
        result = subprocess.run(
            ['grep', '-r', '-E', '(TODO|FIXME)', '--include=*.py', 'src/'],
            cwd=self.repo_path,
            capture_output=True
        )
        return len(result.stdout.decode().strip().split('\n')) if result.stdout else 0
    
    def _calculate_debt_hours(self) -> float:
        """Estimate debt in hours."""
        # Rough formula based on issues
        issues = (
            (100 - self._get_coverage()) * 10 +  # Missing coverage
            self._get_duplication() * 0.5 +        # Duplication
            self._get_security_issues() * 8       # Security fixes
        )
        return issues

# Example: Automated refactoring suggestions
# that encourage incremental improvement

class BoyScoutRefactorer:
    """Tools to apply boy scout rule automatically."""
    
    # Patterns that can be auto-fixed
    AUTO_FIX_PATTERNS = {
        'unused_imports': {
            'detector': 'pyflakes',
            'fixer': 'pyflakes --exit-zero-even-if-changed'
        },
        'import_order': {
            'detector': 'isort --check',
            'fixer': 'isort'
        },
        'code_format': {
            'detector': 'black --check',
            'fixer': 'black'
        },
        'type_hints': {
            'detector': 'mypy',
            'fixer': 'None (manual)'
        }
    }
    
    def apply_auto_fixes(self, paths: List[str]):
        """Apply all auto-fixable refactorings."""
        results = {}
        
        for pattern, config in self.AUTO_FIX_PATTERNS.items():
            if pattern == 'type_hints':
                continue  # Manual fix
            
            result = subprocess.run(
                config['fixer'].split() + paths,
                capture_output=True
            )
            results[pattern] = {
                'success': result.returncode == 0,
                'output': result.stdout.decode()
            }
        
        return results

# Refactoring Sprint Template

## Sprint: [Name] - [Date Range]

### Goals
- [Primary goal - e.g., "Reduce API response time by 50%"]

### Scope
- [Component/System to refactor]
- [Specific debt items from registry]

### Success Metrics
| Metric | Before | Target | After |
|--------|--------|-------|-------|
| Response Time | 500ms | 250ms | - |
| Test Coverage | 60% | 80% | - |
| Complexity | 8.5 | 5.0 | - |

### Daily Plan

#### Day 1: Preparation
- [ ] Review affected code
- [ ] Ensure full test coverage exists
- [ ] Create backup branch
- [ ] Set up monitoring

#### Day 2-3: Refactor Core Logic
- [ ] Extract to smaller functions
- [ ] Remove duplication
- [ ] Add type hints
- [ ] Update tests

#### Day 4: Polish & Verify
- [ ] Run full test suite
- [ ] Performance testing
- [ ] Code review
- [ ] Update documentation

#### Day 5: Deploy
- [ ] Staged rollout
- [ ] Monitor metrics
- [ ] Rollback plan ready
- [ ] Merge to main

# Migration strategy example
# From legacy monolith to microservices

migration_strategy:
  name: "Strangler Fig Pattern"
  phases:
    - phase: 1
      name: "Identify Bounded Contexts"
      activities:
        - Analyze monolith for clear boundaries
        - Identify domain entities
        - Define service contracts
      duration: "2 weeks"
    
    - phase: 2
      name: "Setup Infrastructure"
      activities:
        - Create new service(s)
        - Set up database(s)
        - Configure CI/CD
      duration: "1 week"
    
    - phase: 3
      name: "Implement New Service"
      activities:
        - Implement core functionality
        - Add comprehensive tests
        - Set up monitoring
      duration: "2-4 weeks"
    
    - phase: 4
      name: "Route Traffic (Feature Flag)"
      activities:
        - Add router/proxy
        - Route small percentage to new service
        - Monitor for issues
      duration: "1 week"
    
    - phase: 5
      name: "Increase Traffic"
      activities:
        - Gradually increase traffic
        - Handle edge cases
        - Full cutover when stable
      duration: "1-2 weeks"
    
    - phase: 6
      name: "Remove Legacy Code"
      activities:
        - Verify no remaining references
        - Remove old code
        - Decommission old infrastructure
      duration: "1 week"

feature_flag_example:
  name: "new_order_service"
  rollout:
    - 10% users: week 1
    - 25% users: week 2
    - 50% users: week 3
    - 100% users: week 4
  metrics_to_watch:
    - error_rate
    - latency_p99
    - success_rate

# Example: Using adapter pattern to isolate legacy code
# before full refactoring

# Legacy payment processor (old, hard to maintain)
class LegacyPaymentProcessor:
    """Old payment processor with messy implementation."""
    
    def process_payment(self, amount, card_number, expiry):
        # Old implementation with global state
        global _current_processor
        _current_processor = self
        # ... complex legacy code
        return {"status": "success", "transaction_id": "12345"}
    
    def refund(self, transaction_id, amount):
        # Old refund logic
        return {"status": "success"}

# New clean interface
class PaymentProcessor(ABC):
    """Abstract interface for payment processing."""
    
    @abstractmethod
    def charge(self, amount: Decimal, currency: str, 
               payment_method: PaymentMethod) -> ChargeResult:
        pass
    
    @abstractmethod
    def refund(self, charge_id: str, amount: Decimal 
               ) -> RefundResult:
        pass

# Adapter to wrap legacy code
class LegacyPaymentAdapter(PaymentProcessor):
    """Adapter to wrap legacy payment processor."""
    
    def __init__(self LegacyPaymentProcessor):
, legacy:        self.legacy = legacy
    
    def charge(self, amount: Decimal, currency: str,
               payment_method: PaymentMethod) -> ChargeResult:
        # Convert to legacy format
        card_number = payment_method.card_number
        expiry = payment_method.expiry
        
        # Call legacy with timeout
        try:
            result = self.legacy.process_payment(
                float(amount),
                card_number,
                expiry
            )
            return ChargeResult(
                success=True,
                transaction_id=result['transaction_id']
            )
        except Exception as e:
            return ChargeResult(success=False, error=str(e))
    
    def refund(self, charge_id: str, amount: Decimal) -> RefundResult:
        try:
            result = self.legacy.refund(charge_id, float(amount))
            return RefundResult(success=True)
        except Exception as e:
            return RefundResult(success=False, error=str(e))

# Usage: Code now uses clean interface
class OrderService:
    def __init__(self, payment_processor: PaymentProcessor):
        self.processor = payment_processor
    
    def create_order(self, amount, payment_method):
        result = self.processor.charge(
            amount, "USD", payment_method
        )
        if result.success:
            # Create order
            pass

# Example: Feature flag implementation
# for controlling debt-inducing code paths

import json
from datetime import datetime
from typing import Optional, Callable, Any

class FeatureFlag:
    """Simple feature flag implementation."""
    
    def __init__(self, name: str, enabled: bool = False):
        self.name = name
        self.enabled = enabled
        self.rules: List[Callable] = []
    
    def is_enabled(self, user_context: Optional[dict] = None) -> bool:
        """Check if feature is enabled."""
        # Check custom rules first
        for rule in self.rules:
            if not rule(user_context):
                return False
        return self.enabled
    
    def add_rule(self, rule: Callable[[Optional[dict]], bool]):
        """Add custom rule (e.g., percentage rollout)."""
        self.rules.append(rule)
    
    def __call__(self, func: Callable) -> Callable:
        """Decorator to conditionally execute function."""
        def wrapper(*args, **kwargs):
            if self.is_enabled():
                return func(*args, **kwargs)
            # Fallback behavior
            return None
        return wrapper

# Example: Percentage rollout rule
def percentage_rollout(percentage: int) -> Callable:
    """Create a percentage rollout rule."""
    import random
    def rule(context: Optional[dict]) -> bool:
        if not context or 'user_id' not in context:
            return False
        # Deterministic rollout based on user_id
        user_hash = hash(context['user_id']) % 100
        return user_hash < percentage
    return rule

# Usage
feature_flags = {
    'new_payment_flow': FeatureFlag('new_payment_flow'),
    'refactored_checkout': FeatureFlag('refactored_checkout'),
}

# Configure rollout
feature_flags['new_payment_flow'].enabled = True
feature_flags['refactored_checkout'].add_rule(percentage_rollout(25))

# In code
class CheckoutService:
    def __init__(self):
        self.payment_flow = feature_flags['new_payment_flow']
    
    def process_checkout(self, cart, user_context):
        if self.payment_flow.is_enabled(user_context):
            return self._new_checkout_flow(cart)
        return self._legacy_checkout_flow(cart)

# Example: sonarqube.properties configuration
# sonar-project.properties

sonar.projectKey=my-project
sonar.projectName=My Project
sonar.projectVersion=1.0.0

# Source paths
sonar.sources=src
sonar.tests=tests

# Language settings
sonar.language=py
sonar.sourceEncoding=UTF-8

# Quality gates
sonar.qualitygate.wait=true

# Technical debt thresholds
sonar.python.bands=.0:0,.1000:1,.2000:2,.5000:3
# Bands: 0=Low, 1=Medium, 2=Major, 3=Critical

# Debt calculation
sonar.technicalDebt.rating=0.15
# Maximum allowed technical debt ratio (15%)

# Coverage requirements
sonar.coverage.jacoco.xmlReportPaths=target/site/jacoco/jacoco.xml
sonar.coverage.exclusions=**/*Test*.java,**/test/**

# Recommended: 20% Rule
# Dedicate ~20% of sprint capacity to technical debt

Sprint Capacity: 100 story points
Debt Allocation: 20 points (20%)

Breakdown:
├── Bug fixes: 5 points
├── Small refactorings (Boy Scout): 5 points
├── Test improvements: 5 points
└── Technical debt items from registry: 5 points

# Example: Add TODO/FIXME with proper tagging
# TODO[2026-Q1]: Refactor user authentication
# FIXME[2026-01]: Fix race condition in payment processing
# DEBT: Migrate to new API (TICKET-1234)

# This allows tracking via grep
# grep -r "TODO\|FIXME\|DEBT" --include="*.py" src/

# Example: Reporting debt to stakeholders

## Technical Debt Report - January 2026

### Summary
- Total Debt Items: 47
- Estimated Hours to Fix: 320 hours
- Debt Ratio: 12% (target: <10%)
- Interest Accrued This Quarter: 45 hours

### Top 5 Debt Items by Impact

| # | Item | Impact | Effort | Priority |
|---|------|--------|--------|----------|
| 1 | No rate limiting | 25% slower development on API features | 16h | P0 |
| 2 | Duplicated validation | 15% bug rate increase | 24h | P1 |
| 3 | Missing integration tests | 20% longer releases | 40h | P1 |
| 4 | Outdated auth library | Security risk | 8h | P0 |
| 5 | Tight coupling | 30% slower feature development | 80h | P2 |

### Recommendation
Allocate 2 additional engineers for debt reduction sprint in Q1
Expected ROI: 40% improvement in development velocity