Tech Debt Scanner Skill

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

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

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:

Deduplicate - Remove duplicate findings across categories
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
Group by file - Organize findings by affected file
Calculate debt score - Overall technical debt metric

Step 4: Generate Report

Create actionable report with:

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

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

Interactive prompts:

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

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:

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

#!/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:

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

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

{
  "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:

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

Report Formats

/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

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

Agent Skills: Tech Debt Scanner

Install this agent skill to your local

Skill Files