techdebt

# Tech Debt Scanner

Automated technical debt detection using parallel subagents. Designed to run at session end to catch issues while context is fresh.

## Quick Start

```bash
# Session end - scan changes since last commit (default)
/techdebt

# Deep scan - analyze entire codebase
/techdebt --deep

# Specific categories
/techdebt --duplicates    # Only duplication
/techdebt --security      # Only security issues
/techdebt --complexity    # Only complexity hotspots
/techdebt --deadcode      # Only dead code

# Auto-fix mode (interactive)
/techdebt --fix
```

## Architecture

**Always uses parallel subagents** for fast analysis:

```
Main Agent (orchestrator)
    │
    ├─> Subagent 1: Duplication Scanner
    ├─> Subagent 2: Security Scanner
    ├─> Subagent 3: Complexity Scanner
    └─> Subagent 4: Dead Code Scanner

    ↓ All run in parallel (2-15s depending on scope)

Main Agent: Consolidate findings → Rank by severity → Generate report
```

**Benefits:**
- 🚀 Parallel execution - all scans run simultaneously
- 🧹 Clean main context - no pollution from analysis work
- 💪 Scalable - handles large codebases efficiently
- 🎯 Fast - even small diffs benefit from parallelization

## Workflow

### Step 1: Determine Scope

**Default (no flags):**
- Scan files changed since last commit: `git diff --name-only HEAD`
- Fast session-end workflow (~2-3 seconds)
- Perfect for "wrap up" scenarios

**Deep scan (`--deep` flag):**
- Scan entire codebase
- Comprehensive analysis (~10-15 seconds for medium projects)
- Use when refactoring or preparing major releases

**Specific category (e.g., `--duplicates`):**
- Run only specified scanner
- Fastest option for targeted analysis

### Step 2: Spawn Parallel Subagents

Launch 4 subagents simultaneously (or subset if category specified):

**Subagent 1: Duplication Scanner**
- Task: Find duplicated code blocks using AST similarity
- Tools: `ast-grep`, structural search, token analysis
- Output: List of duplicate code blocks with similarity scores

**Subagent 2: Security Scanner**
- Task: Detect security vulnerabilities and anti-patterns
- Checks: Hardcoded secrets, SQL injection, XSS, insecure crypto
- Output: Security findings with severity and remediation guidance

**Subagent 3: Complexity Scanner**
- Task: Identify overly complex functions and methods
- Metrics: Cyclomatic complexity, nested depth, function length
- Output: Complexity hotspots with refactoring suggestions

**Subagent 4: Dead Code Scanner**
- Task: Find unused imports, variables, and unreachable code
- Checks: Unused imports, dead branches, orphaned functions
- Output: Dead code list with safe removal instructions

**Subagent instructions template:**
```
Scan {scope} for {category} issues.

## Domain Knowledge
Before scanning, read the relevant skill for deeper patterns:
- Security scanner: Read skills/security-ops/references/owasp-detailed.md
- Complexity scanner: Read skills/refactor-ops/SKILL.md

Scope: {file_list or "entire codebase"}
Language: {detected from file extensions}
Focus: {category-specific patterns}

Output format:
- File path + line number
- Issue description
- Severity (P0-P3)
- Suggested fix (if available)

Use appropriate tools:
- Duplication: ast-grep for structural similarity
- Security: pattern matching + known vulnerability patterns
- Complexity: cyclomatic complexity calculation
- Dead Code: static analysis for unused symbols
```

### Step 3: Consolidate Findings

Main agent collects results from all subagents and:

1. **Deduplicate** - Remove duplicate findings across categories
2. **Rank by severity:**
   - **P0 (Critical):** Security vulnerabilities, blocking issues
   - **P1 (High):** Major duplication, high complexity
   - **P2 (Medium):** Minor duplication, moderate complexity
   - **P3 (Low):** Dead code, style issues
3. **Group by file** - Organize findings by affected file
4. **Calculate debt score** - Overall technical debt metric

### Step 4: Generate Report

Create actionable report with:

```markdown
# Tech Debt Report

**Scope:** {X files changed | Entire codebase}
**Scan Time:** {duration}
**Debt Score:** {0-100, lower is better}

## Summary

| Category | Findings | P0 | P1 | P2 | P3 |
|----------|----------|----|----|----|----|
| Duplication | X | - | X | X | - |
| Security | X | X | - | - | - |
| Complexity | X | - | X | X | - |
| Dead Code | X | - | - | X | X |

## Critical Issues (P0)

### {file_path}:{line}
**Category:** {Security}
**Issue:** Hardcoded API key detected
**Impact:** Credential exposure risk
**Fix:** Move to environment variable

## High Priority (P1)

### {file_path}:{line}
**Category:** {Duplication}
**Issue:** 45-line block duplicated across 3 files
**Impact:** Maintenance burden, inconsistency risk
**Fix:** Extract to shared utility function

[... continue for all findings ...]

## Recommendations

1. Address all P0 issues before merge
2. Consider refactoring high-complexity functions
3. Remove dead code to reduce maintenance burden

## Auto-Fix Available

Run `/techdebt --fix` to interactively apply safe automated fixes.
```

### Step 5: Auto-Fix Mode (Optional)

If `--fix` flag provided:

1. **Identify safe fixes:**
   - Dead import removal (safe)
   - Simple duplication extraction (review required)
   - Formatting fixes (safe)

2. **Interactive prompts:**
   ```
   Fix: Remove unused import 'requests' from utils.py:5
   [Y]es / [N]o / [A]ll / [Q]uit
   ```

3. **Apply changes:**
   - Edit files with confirmed fixes
   - Show git diff of changes
   - Prompt for commit

**Safety rules:**
- Never auto-fix security issues (require manual review)
- Never auto-fix complexity (requires design decisions)
- Only auto-fix with explicit user confirmation

## Detection Patterns

### Duplication

**AST Similarity Detection:**
- Use `ast-grep` for structural pattern matching
- Detect code blocks with >80% structural similarity
- Ignore trivial differences (variable names, whitespace)

**Token-based Analysis:**
- Compare token sequences for exact duplicates
- Minimum threshold: 6 consecutive lines
- Group similar duplicates across files

**Thresholds:**
- P1: 30+ lines duplicated in 3+ locations
- P2: 15+ lines duplicated in 2+ locations
- P3: 6+ lines duplicated in 2 locations

### Security

**Pattern Detection:**

| Pattern | Severity | Example |
|---------|----------|---------|
| Hardcoded secrets | P0 | `API_KEY = "sk-..."` |
| SQL injection risk | P0 | `f"SELECT * FROM users WHERE id={user_id}"` |
| Insecure crypto | P0 | `hashlib.md5()`, `random.random()` for tokens |
| Path traversal | P0 | `open(user_input)` without validation |
| XSS vulnerability | P0 | Unescaped user input in HTML |
| Eval/exec usage | P1 | `eval(user_input)` |
| Weak passwords | P2 | Hardcoded default passwords |

**Language-specific checks:**
- Python: `pickle` usage, `yaml.load()` without SafeLoader
- JavaScript: `eval()`, `innerHTML` with user data
- SQL: String concatenation in queries

### Complexity

**Metrics:**

| Metric | P1 Threshold | P2 Threshold |
|--------|--------------|--------------|
| Cyclomatic Complexity | >15 | >10 |
| Function Length | >100 lines | >50 lines |
| Nested Depth | >5 levels | >4 levels |
| Number of Parameters | >7 | >5 |

**Refactoring suggestions:**
- Extract method for long functions
- Introduce parameter object for many parameters
- Simplify conditionals with guard clauses
- Break up deeply nested logic

### Dead Code

**Detection methods:**
- Unused imports (language-specific linters)
- Unreachable code (after return/break/continue)
- Unused variables (written but never read)
- Orphaned functions (never called in codebase)

**Safe removal criteria:**
- No external references found
- Not part of public API
- Not dynamically imported/called

## Language Support

**Tier 1 (Full support):**
- Python: `ast-grep`, `radon`, `pylint`
- JavaScript/TypeScript: `ast-grep`, `eslint`, `jscpd`
- Go: `gocyclo`, `golangci-lint`
- Rust: `clippy`, `cargo-audit`

**Tier 2 (Basic support):**
- Java, C#, Ruby, PHP: Pattern-based detection only

**Language detection:**
- Auto-detect from file extensions
- Use appropriate tools per language
- Fallback to universal patterns if specific tools unavailable

## Integration Patterns

### Session End Automation

Add to your workflow:

```markdown
## Session Wrap-Up Checklist

- [ ] Run `/techdebt` to scan changes
- [ ] Address any P0 issues found
- [ ] Create tasks for P1/P2 items
- [ ] Commit clean code
```

### Pre-Commit Hook

Create `.claude/hooks/pre-commit.sh`:

```bash
#!/bin/bash
# Auto-run tech debt scan before commits

echo "🔍 Scanning for tech debt..."
claude skill techdebt --quiet

if [ $? -eq 1 ]; then
  echo "❌ P0 issues detected. Fix before committing."
  exit 1
fi

echo "✅ No critical issues found"
```

### CI/CD Integration

Run deep scan on pull requests:

```yaml
# .github/workflows/techdebt.yml
name: Tech Debt Check
on: [pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tech debt scan
        run: claude skill techdebt --deep --ci
```

## Advanced Usage

### Baseline Tracking

Track debt over time:

```bash
# Initial baseline
/techdebt --deep --save-baseline

# Compare against baseline
/techdebt --compare-baseline
# Output: "Debt increased by 15% since baseline"
```

Baseline stored in `.claude/techdebt-baseline.json`:

```json
{
  "timestamp": "2026-02-03T10:00:00Z",
  "commit": "a28f0fb",
  "score": 42,
  "findings": {
    "duplication": 8,
    "security": 0,
    "complexity": 12,
    "deadcode": 5
  }
}
```

### Custom Patterns

Add project-specific patterns in `.claude/techdebt-rules.json`:

```json
{
  "security": [
    {
      "pattern": "TODO.*security",
      "severity": "P0",
      "message": "Security TODO must be resolved"
    }
  ],
  "complexity": {
    "cyclomatic_threshold": 12,
    "function_length_threshold": 80
  }
}
```

### Report Formats

```bash
/techdebt --format=json     # JSON output for tooling
/techdebt --format=markdown # Markdown report (default)
/techdebt --format=sarif    # SARIF for IDE integration
```

## Troubleshooting

**Issue: Scan times out**
- Solution: Use `--deep` only on smaller modules, or increase timeout
- Consider: Break large codebases into smaller scan chunks

**Issue: Too many false positives**
- Solution: Adjust thresholds in `.claude/techdebt-rules.json`
- Consider: Use `--ignore-patterns` flag to exclude test files

**Issue: Missing dependencies (ast-grep, etc.)**
- Solution: Install tools via `npm install -g @ast-grep/cli` or skip category
- Fallback: Pattern-based detection still works without specialized tools

## Best Practices

1. **Run at every session end** - Catch debt while context is fresh
2. **Address P0 immediately** - Don't commit critical issues
3. **Create tasks for P1/P2** - Track technical debt in backlog
4. **Use baselines for trends** - Monitor debt accumulation over time
5. **Automate in CI/CD** - Prevent debt from merging
6. **Educate team** - Share findings, discuss refactoring strategies

## References

See also:
- [Anthropic's Agent Skills](https://github.com/anthropics/skills) - Subagent patterns
- [references/patterns.md](references/patterns.md) - Language-specific debt patterns
- [references/severity-guide.md](references/severity-guide.md) - How to rank findings