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.

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:

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)

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

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

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

techdebt

NPX Install

Tags

SKILL.md Content

Tech Debt Scanner

Quick Start

Architecture

Workflow

Step 1: Determine Scope

Step 2: Spawn Parallel Subagents

Step 3: Consolidate Findings

Step 4: Generate Report

Step 5: Auto-Fix Mode (Optional)

Detection Patterns

Duplication

Security

Complexity

Dead Code

Language Support

Integration Patterns

Session End Automation

Pre-Commit Hook

CI/CD Integration

Advanced Usage

Baseline Tracking

Custom Patterns

Report Formats

Troubleshooting

Best Practices

References