Technical Debt Detector

Efficiently identify technical debt in large Python projects using scripts that output targeted file locations, minimizing token cost.

Quick Start

# Full analysis - produces prioritized report
python scripts/analyze_all.py /path/to/project

# JSON output for programmatic use
python scripts/analyze_all.py /path/to/project --format json

# Run specific checks only
python scripts/analyze_all.py /path/to/project --only security testing

Individual Analyzers

Run specific checks when focused analysis is needed:

| Script | Purpose | Key Outputs | |--------|---------|-------------| | analyze_all.py | Master analyzer - runs all checks | Prioritized report with fix sketches | | find_deferred_work.py | TODO/FIXME/HACK/XXX markers | Location + message + severity | | find_security_issues.py | Security vulnerabilities (uses bandit) | CVEs, hardcoded secrets, unsafe patterns | | analyze_test_coverage.py | Missing tests, coverage gaps | Untested modules, empty tests | | find_maintainability_issues.py | Docstrings, type hints, naming | Missing docs, bad names, long functions | | check_dependencies.py | Outdated packages, vulnerabilities | Versions, CVEs, unpinned deps |

Usage Examples

# Find all deferred work
python scripts/find_deferred_work.py /path/to/project
python scripts/find_deferred_work.py . --severity high  # Only FIXME/BUG/HACK/XXX

# Security scan
python scripts/find_security_issues.py /path/to/project

# Test coverage analysis
python scripts/analyze_test_coverage.py /path/to/project
python scripts/analyze_test_coverage.py . --run-coverage  # Include pytest-cov

# Maintainability check
python scripts/find_maintainability_issues.py /path/to/project
python scripts/find_maintainability_issues.py . --check docstrings  # Focus on docs

# Dependency health
python scripts/check_dependencies.py /path/to/project
python scripts/check_dependencies.py . --only vulnerabilities  # Just CVEs

Workflow

1. Run full analysis: python scripts/analyze_all.py /path/to/project
2. Review prioritized report: High → Medium → Low severity
3. For each high-priority item:
   • Navigate to file:line
   • Apply fix sketch from report
   • See references/fix_patterns.md for detailed patterns
4. For complexity/code smells: Use python-simplifier skill

Output Format

All scripts support --format json for integration with other tools:

python scripts/analyze_all.py . --format json | jq '.[] | select(.severity == "high")'

Dependencies

Required (install if not present):

• bandit - Security analysis: pip install bandit
• pip-audit - Vulnerability scanning: pip install pip-audit

Optional (for deeper analysis):

• pytest-cov - Coverage analysis: pip install pytest-cov

Severity Levels

• High 🔴: Fix immediately (security vulnerabilities, FIXME/BUG markers, critical gaps)
• Medium 🟡: Fix soon (TODOs, missing docstrings, outdated dependencies)
• Low 🔵: Fix when convenient (missing type hints, NOTEs, minor style issues)

Relationship to python-simplifier

This skill focuses on deferred work, security, testing, maintainability, and dependencies.

For complexity and code smells (cyclomatic complexity, duplication, coupling, dead code, over-engineering), use the python-simplifier skill.