Purpose
Surface technical debt patterns before they accumulate: duplicates, dead code, complexity hotspots, TODOs, oversized files.
Quick Start
/techdebt # scan current directory
/techdebt src/ # scan specific path
/techdebt --duplicates # only duplicate check
/techdebt --todos # only TODO/FIXME markers
/techdebt --dead-code # only dead code
How to Run
Execute the scan script — it auto-detects Python/JS/TS and skips missing tools:
bash $CLAUDE_SKILL_DIR/scripts/scan.sh [path] [filter-flag]
Then interpret and report the output using the Output Format below. The script handles tool invocation; your job is to classify findings by severity and suggest fixes.
Output Format
Produce a # Tech Debt Report with:
- Summary table — category, count, severity (Low / Medium / High)
- Details per category — file, line, symbol, suggestion
- Quick Fixes — any automatable repairs (
ruff --fix,eslint --fix) - Recommended Actions — prioritized: Immediate / This week / Backlog
Severity thresholds: duplicates (Low ≤2, Medium 3-5, High >5), dead code (Low ≤5, High >10), large functions (Medium >75 lines, High >100), large files (High >1000 lines), complexity CC >10 (Medium).
Tool Reference
Tools the script uses (installed = runs; missing = skipped with note):
| Check | Python | JS/TS |
|---|---|---|
| Duplicates | pylint | jscpd |
| Dead code | vulture | ts-prune |
| Complexity/size | radon | eslint |
| Circular imports | pycycle | madge |
| TODOs | grep (no dep) | grep (no dep) |
Install missing tools: uv add --dev vulture radon pylint / npm install -D jscpd ts-prune madge
Gotchas
.venv,node_modules,dist,__pycache__are auto-excluded by the scan scriptpylint --enable=duplicate-codeis slow on large codebases; warn if scanning >500 filests-pruneonly works from the project root (needstsconfig.json); run from a sub-path → 0 findingsradon cc= per-function cyclomatic complexity;radon raw= per-file LOC — different output formats- Deprecated registry dependency check requires
~/.claude/docs/development/registry.yaml; skip silently if absent