Tech Debt Scanner

The Problem

Your codebase has accumulated invisible debt: TODOs in auth code from 18 months ago, a 980-line billing module that changes every sprint, test-to-source ratio of 0.3 on your most critical paths, and lockfiles nobody has touched since the last framework upgrade. You know it's there — you feel it every time you open a file and spend ten minutes finding where to make the change. But you can't quantify it, you can't prioritize it, and you definitely can't get a sprint backlog out of "yeah, the codebase is messy."

Without a structured scan, tech debt stays in the realm of vibes. Teams argue about what to fix, fix the wrong things, or (most commonly) fix nothing because the problem feels too big to start.

What You Get

• Automated five-category debt scan — comment debt (TODO/FIXME/HACK markers), structural debt (long functions, deep nesting, oversized files), dependency debt (stale lockfiles, EOL packages), test debt (missing tests, skipped tests, low ratios), documentation debt (undocumented APIs, orphaned docs)
• Severity classification with location multipliers — a FIXME in auth code is Critical; one in a demo script is Low. Every finding carries file path, line number, risk statement, and a first remediation step
• Churn-weighted prioritization — debt × change frequency compounds risk. A 600-line file touched 87 times is a higher-priority refactor than a 900-line file touched twice
• Skip-test detection — finds every it.skip, describe.skip, @pytest.mark.skip, and @Ignore annotation, each needing a reason or restoration
• Anti-false-positive filtering — generated code, vendored dependencies, TODOs with owner + ticket numbers, and documented workarounds are suppressed from findings
• Trend-tracking baseline — markdown reports saved in a diffable format so re-scans after remediation sprints show measurable improvement

Why This Beats Prompting It Yourself

A raw grep -rn "TODO|FIXME" . gives you a flat list with zero context — every marker treated equally, no severity, no location intelligence, no churn data. The scanner applies a five-tier location multiplier (auth/payments/crypto → highest; scripts/demos → lowest) that transforms a 400-item grep dump into 15 actionable findings organized by sprint timeline. You get judgment, not just counts.

Example Session

You: "Scan the billing service at ./services/billing/ for tech debt. It's a Python monolith, 40k LOC."

Agent:

# Tech Debt Report — billing-service
Date: 2026-09-21 | Files Scanned: 127 | LOC: 40,200

SUMMARY
═══════
Critical: 3 | High: 4 | Medium: 6 | Low: 2

CRITICAL ITEMS
══════════════
File                  Line  Category      Finding                 First Action
────────────────────  ────  ────────────  ──────────────────────  ────────────────────────
billing_service.py    847   Comment Debt  FIXME in payment        Read surrounding
                                          reconciliation —        function; extract error
                                          security-adjacent, no   handling to dedicated
                                          error handling          module
payment_processor.py  312   Test Debt     Skipped test on         Restore test or document
                                          charge-refund flow —    why it was disabled
                                          highest-churn file (87
                                          commits)
models/invoice.py     1     Structural    980 lines, 6-level      Extract nested
                                          nesting, 12             validation logic into
                                          commits/month           validators/

HIGH ITEMS
══════════
──────────────────  ────  ──────────  ────  ────────────
billing_service.py  234   Comment De

Use Cases

• Pre-release health gate — scan before cutting a release to identify blockers and hidden risks
• Sprint planning input — feed severity-rated findings directly into backlog grooming with estimated remediation effort
• New codebase onboarding — generate a health map before touching unfamiliar code
• Refactor scoping — identify which modules have the highest debt × churn compound risk
• Trend tracking — baseline now, re-sprint, re-scan; the delta is what motivates remediation investment

Known Limitations

The scanner uses regex-based detection, not full AST parsing, so deeply nested or non-standard patterns may require manual review. Dependency staleness and churn analysis require a git repository — results outside git are limited to comment and structural debt only.

Upgrade to Pro

Free measures the debt. Tech Debt Scanner Pro ($5) manages it: debt-vs-churn heatmaps, automated cleanup tickets, architectural-drift tracking, and CI debt budgets. Upgrade when reduction has to survive a sprint plan — Pro version.