techdebt

What this skill does

# 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#