Tech Debt Mode

Identify, catalog, and eliminate technical debt.

Core Philosophy

"Deletion is the most powerful refactoring."

The 40% Rule: In AI-assisted coding, expect to spend 30-40% of your time on code health—reviews, smell detection, and refactoring. Without this investment, vibe-coded bases accumulate invisible debt that slows agents and breeds bugs. Schedule regular code health passes, not just reactive fixes.

Every line of code:

• Must be understood

• Must be tested

• Must be maintained

• Can contain bugs

Less code = less of all the above.

Debt Indicators to Find

Category What to Look For

Comments TODO, FIXME, HACK, XXX, "temporary"

Code Smells Duplicated blocks, long functions (>50 lines)

Type Issues Missing hints, Any types, type: ignore

Dead Code Unused functions, unreachable branches

Dependencies Outdated packages, unused imports

Complexity Deep nesting, long parameter lists

Rationalization Prevention

Excuse Reality Required Action

"Someone might need this code" Dead code is maintenance burden Check references — delete if unused

"It's not hurting anything" Unused code confuses future agents Remove it; git preserves history

"Refactoring is risky" You haven't measured the impact Count callers, assess blast radius first

"We'll clean it up later" Later never comes — debt compounds Fix it now or create a tracked issue with details

"Working code shouldn't be touched" Untouched code rots — dependencies change around it Assess: does it still work? Are patterns current?

Process

1. Scan

Search for debt indicators across the codebase:

• Grep for TODO/FIXME comments

• Find functions over threshold length

• Identify files with type errors

• Check for unused exports

2. Categorize

For each finding, assess:

• Severity: How bad is this?

• Effort: How hard to fix?

• Risk: What could go wrong?

3. Prioritize

Focus on:

• 🎯 Quick Wins - Low effort, high impact

• 🔒 Safety First - Fix risky debt before adding features

• 📍 Hot Paths - Prioritize frequently-touched code

4. Fix or Document

• Simple fixes: Just do it (with tests)

• Complex fixes: Create a plan for later

Quick Win Examples

• Dead imports: Remove unused imports (e.g., from typing import List, Dict, Optional when only Optional is used)

• Bare excepts: Replace except: pass with specific exception handling and logging

• Unused variables: Delete variables that are assigned but never read

Tech Debt Report Format

Tech Debt Analysis

Summary

• Total issues found: X
• Critical: X (fix immediately)
• Quick wins: X (easy to fix)
• Requires planning: X (complex)

Findings

Critical 🔴

Quick Wins 🎯

Requires Planning 📋

Recommendations

[Suggested order of tackling debt]

Fixed This Session

[List of debt items resolved]

When Fixing Debt

• ✅ Run tests after each change

• ✅ Keep changes atomic and focused

• ✅ Verify no regressions

• ❌ Don't mix debt fixes with new features

• ❌ Don't "refactor" working code without reason

Safe Deletion Patterns

Before removing code, verify it's unused:

Check for usages

ag "function_name" --python

Check imports

ag "from module import function_name"

Watch for code that might be used dynamically:

✅ Safe to delete: unused import

from typing import List # 'List' never used in file

✅ Safe to delete: unused variable

result = calculate() # 'result' never read log(value) # This is the actual intent

✅ Safe to delete: dead branch

if False: # Will never execute do_something()

⚠️ Verify first: might be used dynamically

def _helper(): # Underscore suggests private, but check usages pass

❌ Don't delete without checking: exported function

def public_api(): # Might be called by external code pass

Also watch for:

• Dynamically called code (getattr , eval )

• Reflection-based frameworks

• External API contracts

• CLI entry points

Cleaning Checklist

• Unused imports removed
• Unused variables removed
• Dead functions removed
• Commented-out code removed
• Debug statements removed
• Duplicate code consolidated
• Tests still pass
• Types still check

Debt Prevention Tips

Add TODOs with issue tracker links, use type hints from the start, and review for simplification opportunities.

"The best code is no code at all."