# Tech Debt Report

**Generated:** {timestamp}
**Scope:** {scope_description}
**Scan Time:** {duration}
**Debt Score:** {score}/100

---

## Executive Summary

{summary_paragraph}

**Key Findings:**
- {finding_count} total issues found
- {p0_count} critical issues requiring immediate action
- {p1_count} high-priority issues to address soon
- Debt score is {trend} compared to baseline

---

## Summary Statistics

| Category | Findings | P0 | P1 | P2 | P3 |
|----------|----------|----|----|----|----|
| 🔄 Duplication | {dup_total} | {dup_p0} | {dup_p1} | {dup_p2} | {dup_p3} |
| 🔒 Security | {sec_total} | {sec_p0} | {sec_p1} | {sec_p2} | {sec_p3} |
| 📊 Complexity | {cplx_total} | {cplx_p0} | {cplx_p1} | {cplx_p2} | {cplx_p3} |
| 💀 Dead Code | {dead_total} | {dead_p0} | {dead_p1} | {dead_p2} | {dead_p3} |
| **Total** | **{total}** | **{p0_total}** | **{p1_total}** | **{p2_total}** | **{p3_total}** |

---

## Critical Issues (P0) 🚨

{if p0_count > 0}
{for each p0_finding}
### {file_path}:{line_number}

**Category:** {category}
**Issue:** {issue_description}
**Impact:** {impact_description}
**Recommendation:** {fix_suggestion}

```{language}
{code_snippet}
```

**Fix:**
```{language}
{fixed_code_snippet}
```

---
{end for}
{else}
✅ No critical issues found.
{endif}

---

## High Priority (P1) ⚠️

{if p1_count > 0}
{for each p1_finding}
### {file_path}:{line_number}

**Category:** {category}
**Issue:** {issue_description}
**Impact:** {impact_description}
**Recommendation:** {fix_suggestion}

```{language}
{code_snippet}
```

---
{end for}
{else}
✅ No high-priority issues found.
{endif}

---

## Medium Priority (P2) 📋

{if p2_count > 0}
<details>
<summary>Show {p2_count} medium-priority findings</summary>

{for each p2_finding}
### {file_path}:{line_number}

**Category:** {category}
**Issue:** {issue_description}
**Fix:** {fix_suggestion}

---
{end for}

</details>
{else}
✅ No medium-priority issues found.
{endif}

---

## Low Priority (P3) 🧹

{if p3_count > 0}
<details>
<summary>Show {p3_count} low-priority findings</summary>

{for each p3_finding}
- **{file_path}:{line_number}** - {issue_description}
{end for}

</details>
{else}
✅ No low-priority issues found.
{endif}

---

## Trends

{if baseline_exists}
### Comparison to Baseline

**Baseline:** {baseline_date} (commit {baseline_commit})

| Metric | Baseline | Current | Change |
|--------|----------|---------|--------|
| Debt Score | {baseline_score} | {current_score} | {score_delta} |
| P0 Issues | {baseline_p0} | {current_p0} | {p0_delta} |
| P1 Issues | {baseline_p1} | {current_p1} | {p1_delta} |
| Total Findings | {baseline_total} | {current_total} | {total_delta} |

**Trend:** {trend_description}

{else}
No baseline found. Run `/techdebt --save-baseline` to start tracking trends.
{endif}

---

## Recommendations

### Immediate Actions

{if p0_count > 0}
1. **Address all {p0_count} P0 issues before merging**
   - These represent security or data integrity risks
   - Estimated fix time: {p0_fix_time}
{else}
✅ No immediate actions required
{endif}

### Short-Term (This Sprint)

{if p1_count > 0}
1. **Refactor {high_complexity_count} high-complexity functions**
   - Start with most frequently modified files
   - Estimated time: {p1_fix_time}

2. **Eliminate major code duplication**
   - {dup_p1_count} instances of significant duplication
   - Extract to shared utilities
{else}
✅ No urgent refactoring needed
{endif}

### Medium-Term (This Quarter)

{if p2_count > 0}
1. **Code cleanup sprint**
   - Address {p2_count} medium-priority issues
   - Focus on {top_p2_category}

2. **Establish debt baseline**
   - Track trends over time
   - Set improvement goals
{endif}

### Long-Term

1. **Prevent new debt**
   - Add pre-commit hooks for tech debt scanning
   - Include in CI/CD pipeline
   - Set quality gates for PRs

2. **Regular debt reviews**
   - Weekly P1 triage
   - Monthly full scans
   - Quarterly architectural reviews

---

## Files Analyzed

{file_list_with_counts}

**Total:** {total_files} files, {total_lines} lines analyzed

---

## Auto-Fix Available

{if auto_fix_count > 0}
The following {auto_fix_count} issues can be automatically fixed:

{for each auto_fix}
- [ ] {file_path}:{line_number} - {fix_description}
{end for}

Run `/techdebt --fix` to apply these changes interactively.
{else}
No safe auto-fixes available. All issues require manual review.
{endif}

---

## Next Steps

1. **Review this report** with your team
2. **Address P0 issues** immediately
3. **Create tickets** for P1 findings
4. **Schedule refactoring** for high-impact areas
5. **Track progress** with baseline comparisons

---

*Generated by claude-mods techdebt skill v1.0*

# Language-Specific Tech Debt Patterns

Detection patterns for common technical debt across programming languages.

## Python

### Duplication Patterns

**Import duplication:**
```python
# Bad: Repeated logic across modules
# file1.py
def process_user(user):
    if not user.email:
        raise ValueError("Email required")
    return user.save()

# file2.py
def update_user(user):
    if not user.email:
        raise ValueError("Email required")
    return user.save()

# Fix: Extract to shared validator
```

**Algorithm duplication:**
```python
# Pattern: Same calculation logic in multiple places
# Detection: AST similarity >85% for blocks >10 lines
```

### Security Patterns

**Hardcoded secrets:**
```python
API_KEY = "sk-1234567890abcdef"  # P0
PASSWORD = "admin123"             # P0
SECRET_TOKEN = "abc" * 10         # P0

# Patterns to detect:
- Uppercase variables with "KEY", "SECRET", "PASSWORD", "TOKEN"
- String values matching common secret formats (sk-, ghp_, aws_)
```

**SQL injection:**
```python
# Bad
query = f"SELECT * FROM users WHERE id={user_id}"  # P0
cursor.execute("SELECT * FROM users WHERE name='" + name + "'")  # P0

# Good
cursor.execute("SELECT * FROM users WHERE id=?", (user_id,))
```

**Insecure crypto:**
```python
import hashlib
hashlib.md5(password)          # P0 - Use bcrypt/scrypt
hashlib.sha1(password)         # P0 - Use bcrypt/scrypt

import random
token = random.random()        # P0 - Use secrets module

import pickle
pickle.loads(user_data)        # P1 - Unsafe deserialization

import yaml
yaml.load(config)              # P1 - Use yaml.safe_load()
```

**Path traversal:**
```python
# Bad
file_path = request.GET['file']
open(file_path)                # P0 - No validation

# Good
file_path = os.path.basename(request.GET['file'])
open(os.path.join(SAFE_DIR, file_path))
```

### Complexity Patterns

**Deeply nested conditionals:**
```python
# P1: >5 levels deep
def process(data):
    if data:
        if data.user:
            if data.user.role:
                if data.user.role == 'admin':
                    if data.user.permissions:
                        if 'delete' in data.user.permissions:
                            # Action here - 6 levels deep
                            pass

# Fix: Use guard clauses and early returns
```

**Long functions:**
```python
# P1: >100 lines
# P2: >50 lines
# Suggest: Extract method refactoring
```

**Many parameters:**
```python
# P2: >5 parameters
def create_user(name, email, age, address, phone, role, department):
    pass

# Fix: Use dataclass or parameter object
```

### Dead Code Patterns

**Unused imports:**
```python
import os          # Used
import sys         # Unused - P3
from typing import List  # Used
from typing import Dict  # Unused - P3
```

**Unreachable code:**
```python
def process():
    return True
    print("Never executed")  # P3 - Unreachable
```

**Unused variables:**
```python
def calculate(x, y):
    result = x + y    # Written but never read - P3
    return x * y
```

## JavaScript/TypeScript

### Duplication Patterns

**React component duplication:**
```typescript
// Bad: Similar components with slight variations
const UserCard = ({ user }) => (
  <div className="card">
    <h2>{user.name}</h2>
    <p>{user.email}</p>
  </div>
);

const ProductCard = ({ product }) => (
  <div className="card">
    <h2>{product.name}</h2>
    <p>{product.price}</p>
  </div>
);

// Fix: Generic Card component with props
```

### Security Patterns

**XSS vulnerabilities:**
```typescript
// Bad
element.innerHTML = userInput;  // P0
document.write(userData);       // P0
$(selector).html(userContent);  // P0

// Good
element.textContent = userInput;
```

**Eval usage:**
```typescript
eval(userCode);                 // P0
new Function(userCode)();       // P0
setTimeout(userCode, 1000);     // P1 if userCode is string
```

**Insecure random:**
```typescript
// Bad
const token = Math.random().toString(36);  // P0

// Good
const token = crypto.randomBytes(32).toString('hex');
```

### Complexity Patterns

**Callback hell:**
```typescript
// P2: >3 levels of nesting
getData((data) => {
  processData(data, (processed) => {
    saveData(processed, (result) => {
      notifyUser(result, (notification) => {
        // 4 levels deep
      });
    });
  });
});

// Fix: Use Promises or async/await
```

**Long switch statements:**
```typescript
// P2: >10 cases
switch (action.type) {
  case 'ACTION_1': /* ... */ break;
  case 'ACTION_2': /* ... */ break;
  // ... 15 more cases
}

// Fix: Use strategy pattern or object lookup
```

### Dead Code Patterns

**Unused imports:**
```typescript
import React from 'react';        // Used
import { useState } from 'react'; // Unused - P3
```

**Dead branches:**
```typescript
if (false) {
  // Never executed - P3
}

const DEBUG = false;
if (DEBUG) {
  // Dead code - P3
}
```

## Go

### Duplication Patterns

**Error handling duplication:**
```go
// Bad: Repeated error handling
result1, err := operation1()
if err != nil {
    log.Printf("Error in operation1: %v", err)
    return nil, err
}

result2, err := operation2()
if err != nil {
    log.Printf("Error in operation2: %v", err)
    return nil, err
}

// Fix: Extract error handler
```

### Security Patterns

**SQL injection:**
```go
// Bad
query := "SELECT * FROM users WHERE id=" + userId  // P0
db.Query(query)

// Good
db.Query("SELECT * FROM users WHERE id=?", userId)
```

**Insecure TLS:**
```go
// Bad
&tls.Config{
    InsecureSkipVerify: true,  // P0
}

// Good
&tls.Config{
    MinVersion: tls.VersionTLS12,
}
```

### Complexity Patterns

**Deep interface nesting:**
```go
// P2: Multiple type assertions in one function
func process(data interface{}) {
    if v, ok := data.(map[string]interface{}); ok {
        if inner, ok := v["key"].([]interface{}); ok {
            if item, ok := inner[0].(string); ok {
                // 3 levels deep
            }
        }
    }
}
```

### Dead Code Patterns

**Unused imports:**
```go
import (
    "fmt"  // Used
    "os"   // Unused - P3
)
```

**Unreachable returns:**
```go
func process() error {
    return nil
    return errors.New("never reached")  // P3
}
```

## Rust

### Duplication Patterns

**Error conversion duplication:**
```rust
// Bad: Repeated error conversion logic
let file1 = File::open("file1.txt")
    .map_err(|e| format!("Failed to open file1: {}", e))?;

let file2 = File::open("file2.txt")
    .map_err(|e| format!("Failed to open file2: {}", e))?;

// Fix: Extract error conversion helper
```

### Security Patterns

**Unsafe blocks:**
```rust
// P1: Any unsafe block requires review
unsafe {
    // Requires careful audit
}
```

**Unwrap in production:**
```rust
// P2: Unwrap can panic
let value = result.unwrap();  // P2 - Use ? or match instead
```

### Complexity Patterns

**Deep match nesting:**
```rust
// P2: >4 levels
match outer {
    Some(x) => match x {
        Ok(y) => match y {
            Some(z) => match z {
                Valid(v) => {
                    // 4 levels deep
                }
                _ => {}
            }
            _ => {}
        }
        _ => {}
    }
    _ => {}
}

// Fix: Use if-let chains or early returns
```

## SQL

### Duplication Patterns

**Repeated CTEs:**
```sql
-- Bad: Same CTE in multiple queries
WITH active_users AS (
  SELECT * FROM users WHERE status = 'active'
)
SELECT * FROM active_users WHERE role = 'admin';

-- Same CTE repeated in another query
-- Fix: Create materialized view
```

### Security Patterns

**SQL injection in dynamic SQL:**
```sql
-- Bad: String concatenation
EXECUTE 'SELECT * FROM ' || table_name;  -- P0

-- Good: Use prepared statements
```

### Complexity Patterns

**Overly complex queries:**
```sql
-- P1: >5 JOINs in single query
-- P2: >3 subqueries nested
-- Fix: Break into CTEs or temporary tables
```

## Cross-Language Patterns

### Magic Numbers

**Pattern:** Unexplained numeric constants
```
# Any language
timeout = 3600  # P3 - Should be named constant
rate_limit = 100  # P3 - Should be config
```

### TODOs and FIXMEs

**Pattern:** Age-based tracking
```
# P1: >90 days old
# P2: >30 days old
# P3: <30 days old

# Use git blame to determine age:
git blame -L <line>,<line> <file> | awk '{print $1}' | xargs git show -s --format=%ci
```

### Long Functions

**Universal threshold:**
- P1: >150 lines (any language)
- P2: >75 lines (any language)

### Commented-Out Code

**Pattern:** Code blocks commented instead of deleted
```
// P3: Remove dead code, rely on git history
/*
def old_implementation():
    # 50 lines of commented code
*/
```

## Detection Tools by Language

| Language | Duplication | Security | Complexity | Dead Code |
|----------|-------------|----------|------------|-----------|
| Python | `ast-grep`, `jscpd` | `bandit`, `semgrep` | `radon`, `mccabe` | `vulture`, `pylint` |
| JavaScript | `jscpd`, `ast-grep` | `eslint-plugin-security` | `eslint` | `eslint` |
| TypeScript | `jscpd`, `ast-grep` | `eslint-plugin-security` | `eslint` | `eslint` |
| Go | `gocyclo`, `ast-grep` | `gosec`, `staticcheck` | `gocyclo` | `golangci-lint` |
| Rust | `ast-grep` | `cargo-audit`, `clippy` | `cargo-clippy` | `cargo-clippy` |
| Java | `pmd`, `jscpd` | `spotbugs`, `pmd` | `pmd` | `pmd` |

## Custom Pattern Matching

For languages without specialized tools, use regex patterns:

```python
# Hardcoded secrets (universal)
r'(password|passwd|pwd|secret|token|api[_-]?key)\s*=\s*["\'][^"\']{8,}["\']'

# SQL injection markers (universal)
r'(execute|query|sql)\s*\(\s*["\'].*?\+.*?["\']'

# Magic numbers (universal, excluding 0, 1, -1, 100, 1000)
r'\b(?!0\b|1\b|-1\b|100\b|1000\b)\d{2,}\b'
```

# Severity Classification Guide

How to rank technical debt findings by severity and impact.

## Severity Levels

| Level | Label | Action Required | Examples |
|-------|-------|-----------------|----------|
| **P0** | Critical | Block merge | Security vulnerabilities, data loss risks |
| **P1** | High | Address soon | Major duplication, high complexity |
| **P2** | Medium | Plan to fix | Minor duplication, moderate complexity |
| **P3** | Low | Nice to have | Dead code, style issues, minor TODOs |

## Classification Framework

### Security Issues → P0 (Critical)

**Criteria:**
- Exposes sensitive data
- Enables unauthorized access
- Allows code injection
- Compromises system integrity

**Examples:**
- Hardcoded API keys, passwords, tokens
- SQL injection vulnerabilities
- XSS vulnerabilities
- Path traversal risks
- Insecure cryptography (MD5, SHA1 for passwords)
- Unsafe deserialization
- Missing authentication checks

**Action:** Fix immediately, block merge until resolved

### Data Integrity → P0 (Critical)

**Criteria:**
- Risk of data corruption
- Inconsistent state possible
- Transaction safety compromised

**Examples:**
- Race conditions in critical paths
- Missing database constraints
- Improper error handling in transactions
- Lack of input validation on critical fields

**Action:** Fix before deploying to production

### Major Duplication → P1 (High)

**Criteria:**
- 30+ lines duplicated
- Duplicated across 3+ files
- Core business logic duplicated
- High maintenance burden

**Impact:**
- Bug fixes must be applied multiple times
- Inconsistencies between copies
- Increased testing burden

**Action:** Refactor within current sprint/milestone

**Refactoring strategies:**
- Extract shared function/method
- Create utility module
- Implement template method pattern
- Use composition over duplication

### High Complexity → P1 (High)

**Criteria:**
- Cyclomatic complexity >15
- Function length >100 lines
- Nested depth >5 levels
- Difficult to test/maintain

**Impact:**
- Bug-prone code
- Hard to understand and modify
- Testing becomes expensive
- Knowledge silos form

**Action:** Simplify when next touching this code

**Refactoring strategies:**
- Extract method
- Replace conditionals with polymorphism
- Introduce guard clauses
- Break into smaller functions

### Minor Duplication → P2 (Medium)

**Criteria:**
- 15-30 lines duplicated
- Duplicated in 2 files
- Utility/helper logic duplicated
- Moderate maintenance burden

**Action:** Track in backlog, address during related work

### Moderate Complexity → P2 (Medium)

**Criteria:**
- Cyclomatic complexity 10-15
- Function length 50-100 lines
- Nested depth 4-5 levels
- Testable but challenging

**Action:** Consider refactoring when adding features

### Dead Code → P3 (Low)

**Criteria:**
- Unused imports
- Unreachable code blocks
- Orphaned functions/classes
- Commented-out code

**Impact:**
- Clutter and confusion
- False positives in searches
- Maintenance overhead
- Misleading context

**Action:** Remove during code cleanup sessions

**Safe removal checklist:**
- Verify no dynamic references (reflection, eval, etc.)
- Check not part of public API
- Confirm not referenced in documentation
- Use git for history, not comments

### Trivial Issues → P3 (Low)

**Criteria:**
- Minor style inconsistencies
- Recent TODOs (<30 days old)
- Small magic numbers
- Minor naming issues

**Action:** Fix opportunistically or ignore

## Special Cases

### Age-Based Adjustments

**Old TODOs:**
- >90 days → P1 (likely forgotten, needs resolution)
- 30-90 days → P2 (track and prioritize)
- <30 days → P3 (fresh, being actively worked on)

**Rationale:** Old TODOs indicate unresolved design decisions or deferred work that should be addressed.

### Context-Based Adjustments

**Critical paths (auth, payment, data processing):**
- Elevate all findings by one level
- P2 complexity → P1 in payment processing
- P3 dead code → P2 in authentication

**Test code:**
- Reduce all findings by one level
- P1 duplication → P2 in test fixtures
- Allow higher complexity in integration tests

**Example code/documentation:**
- Ignore most issues
- Focus only on security P0s

### Team Velocity Adjustments

**Fast-moving startups:**
- Focus on P0 only
- Track P1 but don't block
- P2/P3 for cleanup sprints

**Mature products:**
- Strict P0/P1 enforcement
- Regular P2 addressing
- Zero-debt goal for critical modules

## Decision Matrix

Use this matrix when severity is ambiguous:

| Question | Yes → Higher | No → Lower |
|----------|-------------|------------|
| Is this in a critical path? | +1 level | 0 |
| Does it affect end users directly? | +1 level | 0 |
| Has this caused bugs before? | +1 level | 0 |
| Is this code frequently modified? | +1 level | 0 |
| Would fixing this take >2 hours? | -1 level | 0 |
| Is there a documented plan to fix? | -1 level | 0 |

**Example:**
- Base: P2 (moderate complexity in utility function)
- Critical path? No (0)
- Affects users? No (0)
- Caused bugs? Yes (+1 → P1)
- Frequently modified? Yes (+1 → P0)
- **Final:** P0 (block merge)

## Auto-Fix Eligibility

Only certain findings can be auto-fixed safely:

**Eligible (with confirmation):**
- Unused imports (P3)
- Formatting issues (P3)
- Simple dead code removal (P3)
- Magic number extraction to const (P3)

**Not eligible (manual review required):**
- All security issues (P0)
- Complexity refactoring (P1/P2)
- Duplication extraction (P1/P2)
- Architecture changes (any)

## Reporting Guidelines

### Summary Statistics

Always include in reports:

```
Total findings: 42
├─ P0: 2 (BLOCK MERGE)
├─ P1: 8 (Address soon)
├─ P2: 15 (Plan to fix)
└─ P3: 17 (Nice to have)

Debt Score: 38/100 (lower is better)
```

**Debt Score Formula:**
```
Score = (P0 * 50) + (P1 * 10) + (P2 * 5) + (P3 * 1)
Normalized to 0-100 scale based on codebase size
```

### Trend Tracking

Show changes over time:

```
Debt Score: 38 (↓12% from baseline)

Category changes since baseline:
├─ Duplication: 12 findings (↓3)
├─ Security: 0 findings (✓ no change)
├─ Complexity: 18 findings (↑2)
└─ Dead Code: 12 findings (↓8)

✓ Good: Security issues resolved
⚠ Watch: Complexity trending up
```

### Actionable Recommendations

Prioritize by impact:

```
## Immediate Actions (P0)

1. Remove hardcoded API key in config.py:42
   └─ Impact: Security breach risk
   └─ Fix: Move to environment variable
   └─ Time: 5 minutes

2. Fix SQL injection in users.py:156
   └─ Impact: Database compromise
   └─ Fix: Use parameterized query
   └─ Time: 10 minutes

## High Priority (P1)

3. Refactor process_payment() - 125 lines, complexity 18
   └─ Impact: Bug-prone, hard to test
   └─ Fix: Extract validation, calculation, and persistence
   └─ Time: 2 hours

[... continue with ranked list ...]
```

## Exceptions and Suppressions

Sometimes technical debt is acceptable:

### Suppress findings

Add comments to justify:

```python
# techdebt: suppress complexity - intentionally complex
# reason: Performance-critical path, optimized algorithm
# reviewed: 2026-02-01 by @username
def highly_optimized_function():
    # 150 lines of complex but necessary code
    pass
```

**Valid suppression reasons:**
- Performance optimization (with benchmarks)
- External API compatibility (can't change)
- Temporary workaround (with ticket reference)
- Generated code (with generator version)

**Invalid reasons:**
- "Will fix later" (create ticket instead)
- "No time" (prioritize properly)
- "Works fine" (doesn't address debt)

### Document technical debt decisions

For intentional debt:

```markdown
## Known Technical Debt

| Component | Issue | Reason | Plan |
|-----------|-------|--------|------|
| payment.py | Duplication with refund.py | Rapid prototyping | Refactor in Q2 (PROJ-123) |
| auth.py | High complexity | Legacy system | Migrate to new auth in v3.0 |
```

## Review Process

### Pre-Merge Checklist

- [ ] All P0 issues resolved
- [ ] P1 issues tracked in backlog (with tickets)
- [ ] Debt score not increased significantly
- [ ] New code doesn't introduce P0/P1 debt

### Regular Debt Reviews

**Weekly:** Review new P1 findings, prioritize fixes

**Monthly:** Full scan, track trends, set improvement goals

**Quarterly:** Architectural review, major refactorings

## Calibration Examples

Learn from these real-world examples:

**Example 1: Hardcoded secret**
```python
API_KEY = "sk-abc123def456"  # Severity: P0
```
- Impact: Credential exposure
- Fix time: 5 minutes
- Can't wait: Yes
- **Verdict: P0 (block merge)**

**Example 2: Duplicated validation (30 lines, 3 files)**
```python
# Same 30-line validation in user.py, admin.py, api.py
```
- Impact: Inconsistent validation
- Fix time: 1 hour
- Can wait: Until next feature in module
- **Verdict: P1 (address soon)**

**Example 3: Complex function (95 lines, complexity 12)**
```python
def process_order():  # 95 lines, complexity 12
```
- Impact: Hard to modify
- Fix time: 2 hours
- Can wait: Yes, if tests are good
- **Verdict: P2 (plan to fix)**

**Example 4: Unused import**
```python
import os  # Never used
```
- Impact: Clutter
- Fix time: 1 second
- Can wait: Yes
- **Verdict: P3 (clean up when convenient)**