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:

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:

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

Language-specific checks:

• Python: pickle usage, yaml.load() without SafeLoader
• JavaScript: eval(), innerHTML with user data
• SQL: String concatenation in queries

Complexity

Metrics:

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

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 - Subagent patterns
• references/patterns.md - Language-specific debt patterns
• references/severity-guide.md - How to rank findings