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

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

References

See also:

• Anthropic's Agent Skills - Subagent patterns

• references/patterns.md - Language-specific debt patterns

• references/severity-guide.md - How to rank findings