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

• Run full analysis: python scripts/analyze_all.py /path/to/project

• Review prioritized report: High → Medium → Low severity

• For each high-priority item:

• Navigate to file:line

• Apply fix sketch from report

• See references/fix_patterns.md for detailed patterns

• 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.