aj-geddes/technical-debt

<!-- Last reviewed: 2026-03 -->

Technical Debt Management

Debt Quadrant (Classification)

                    Reckless                    Prudent
              +---------------------+---------------------+
 Deliberate   |  "We don't have    |  "We must ship      |
              |   time for tests"   |   now and deal      |
              |   [DANGEROUS]       |   with consequences"|
              |                     |   [STRATEGIC]       |
              +---------------------+---------------------+
 Inadvertent  |  "What's a         |  "Now we know how   |
              |   design pattern?"  |   we should have    |
              |   [INCOMPETENCE]    |   done it"          |
              |                     |   [LEARNING]        |
              +---------------------+---------------------+

| Quadrant | Action | |----------|--------| | Prudent + Deliberate | Target. Track and schedule paydown. | | Inadvertent + Prudent | Acceptable. Convert to tracked item. | | Reckless + Deliberate | Dangerous. Escalate; requires paydown plan before merge. | | Reckless + Inadvertent | Unacceptable. Training issue, not debt. |

Debt Recognition Signals

Code Smells

• "Just for now" / "temporary" comments
• Copy-paste blocks (DRY violation)
• Commented-out code
• TODO/FIXME/HACK without tracking ID
• Magic numbers, hardcoded config
• Broad exception catching (except: pass)
• Missing error handling or input validation

Test Smells

• Missing coverage, disabled/skipped tests
• No edge case or integration tests
• Manual-only testing

Architecture Smells

• Tight coupling, circular dependencies
• God objects, feature envy, data clumps

Infrastructure Smells

• Outdated dependencies, known CVEs
• No monitoring/logging, manual deploys
• Secrets in code, no backup plan

Debt Tracking Template

technical_debt_item:
  id: TD-042
  type: deliberate        # deliberate | inadvertent
  quadrant: prudent-deliberate
  location: src/auth/login.py:45-89
  description: >
    Hardcoded session timeout to 30 minutes. Should be
    configurable per environment.
  why_taken: >
    Config system not ready; needed auth for demo.
  impact:
    - Cannot adjust without redeploy
    - Different envs need different values
  interest: >
    ~2 hours per incident, ~3 incidents/month = 72 hours/year
  payoff_plan:
    effort: 2 hours
    tasks:
      - Add timeout config to settings
      - Update login.py to read config
      - Add tests for timeout values
      - Deploy to all environments
  priority: high
  created: 2025-01-15
  owner: "@developer"
  due_date: 2025-02-01
  status: tracked  # tracked | scheduled | in_progress | paid

Inline marker format: # TODO(TD-042): Hardcoded timeout, see debt tracker

Debt Lifecycle

1. Identify

Trigger: shortcut taken, suboptimal code found, surprising behavior, repeated patterns.

Classify immediately:

• Deliberate or inadvertent?
• Prudent or reckless?
• What is the ongoing cost (interest)?

2. Document

• Assign ID (TD-XXX)
• Record location (file:line-line)
• Capture WHY debt was taken
• List concrete impacts
• Estimate interest and payoff effort
• Add inline TODO(TD-XXX) comment

3. Calculate Interest

Annual Interest = Cost per Incident x Incidents per Year

| Frequency | Multiplier | |-----------|-----------| | Daily | x 365 | | Weekly | x 52 | | Monthly | x 12 | | Quarterly | x 4 |

Examples:

• Hardcoded config: 2h/incident x 36/year = 72 hours/year
• Missing tests: 1h/bug x 120/year = 120 hours/year
• Copy-paste code: 0.5h/change x 240/year = 120 hours/year

4. Prioritize

Priority Score = Annual Interest / Payoff Effort

| Score | Priority | Payback Period | |-------|----------|---------------| | > 10 | HIGH | < 1 month | | 3-10 | MEDIUM | 1-4 months | | < 3 | LOW | > 4 months |

Examples:

• Missing validation: 120h / 2h = 60 (HIGH)
• Hardcoded config: 72h / 2h = 36 (HIGH)
• Refactor structure: 20h / 16h = 1.25 (LOW)

5. Plan Payment

• Sprint 0 Rule: Address high-priority debt before new features
• 20% Rule: Allocate 20% of sprint capacity to debt
• Boy Scout Rule: Fix small debt when touching nearby code

Payment workflow:

1. Branch: debt/TD-042-description
2. Write characterization tests first
3. Make incremental changes
4. Verify behavior preserved
5. Update tracker: status: paid, record actual_effort
6. Commit: fix(TD-042): make session timeout configurable

6. Verify Payment

• [ ] Root cause addressed (not just symptom)
• [ ] Tests added to prevent regression
• [ ] Documentation updated
• [ ] No new debt introduced
• [ ] Tracker updated to "paid"
• [ ] Inline TODO comments removed

Boy Scout Rule

Leave the code better than you found it.

Small improvements (do these inline):

• Rename unclear variables
• Add missing docstrings
• Extract magic numbers to named constants
• Add type hints to untyped signatures

Large changes (separate commits):

• Do NOT refactor entire modules while adding features
• Do NOT change architecture during bug fixes
• Commit 1: feature/fix only; Commit 2: refactoring only

Debt Prevention Checklist

Definition of Done

• [ ] Tests written and passing
• [ ] Error handling added
• [ ] No hardcoded values
• [ ] No TODOs without debt tracking ID
• [ ] Code reviewed
• [ ] Documentation updated

Review Gate

• [ ] Any "temporary" solutions?
• [ ] Any hardcoded values?
• [ ] Edge cases tested?
• [ ] Would you want to maintain this?

Automated Detection

grep -r "TODO\|FIXME\|HACK" src/ | grep -v "TD-[0-9]"  # Untracked TODOs
bandit -r src/                                            # Security issues
pip list --outdated                                       # Stale dependencies

Debt Budget

• Max 10 open items per module
• High-priority: pay within 30 days
• Medium-priority: pay within 90 days
• Low-priority: review quarterly (pay or close)
• Budget exceeded: stop new features, pay debt first

Debt Communication

| Don't Say | Do Say | |-----------|--------| | "We have technical debt" | "This shortcut costs us 10 hours/month in bug fixes" | | "We need to refactor" | "Paying this debt reduces deployment from 2h to 15min" | | "The code is messy" | "New features take 3x longer; investing 1 week saves 2 weeks/quarter" | | "We should rewrite it" | "Incremental fixes over 3 sprints eliminate 80% of incidents" |

See references/debt-communication.md for standup, sprint planning, and retrospective templates.

Anti-Patterns

| Anti-Pattern | Fix | |-------------|-----| | Debt Bankruptcy ("rewrite from scratch") | Incremental refactoring with tests | | Hidden Debt (shortcuts without docs) | Document immediately, assign ID | | Eternal TODOs (years-old comments) | Convert to tracked items or delete | | Debt as Excuse ("can't add features") | Quantify impact, prioritize, schedule |

Reference Files

• references/debt-examples.md - Before/after examples (TD-050, TD-051, TD-052)
• references/debt-communication.md - Team communication templates