Technical Debt Management for Engineering Leaders

debt_types:
  deliberate_prudent:
    description: "Ship now, refactor later"
    example: Hardcoded config to meet deadline
    characteristic: Conscious trade-off with plan

  deliberate_reckless:
    description: "No time for design"
    example: Skip architecture review
    characteristic: Conscious choice without plan

  inadvertent_prudent:
    description: "Now we know a better way"
    example: Better pattern emerged after implementation
    characteristic: Learning reveals better approach

  inadvertent_reckless:
    description: "What's layering?"
    example: Spaghetti code from inexperience
    characteristic: Quality issues from lack of knowledge

debt_characteristics:
  principal:
    - The original shortcut or suboptimal code
    - Remains constant until addressed

  interest:
    - Ongoing cost of working around debt
    - Slower development
    - More bugs
    - Higher cognitive load
    - Compounds over time

  bankruptcy:
    - When interest exceeds capacity
    - System becomes unmaintainable
    - Rewrite becomes only option

debt_symptoms:
  code_level:
    - High cyclomatic complexity
    - Long methods/classes
    - Duplicated code
    - Missing tests
    - Outdated dependencies

  system_level:
    - Slow deployments
    - High incident rate
    - Difficult onboarding
    - Fear of changes
    - "Don't touch that code"

  process_level:
    - PRs take forever to review
    - Stories often blocked
    - Estimates consistently wrong
    - Lots of "quick fixes"

debt_metrics:
  code_quality:
    tool: SonarQube, CodeClimate
    metrics:
      - Technical debt ratio
      - Code smells
      - Test coverage
      - Duplication percentage

  velocity_impact:
    measure: Time in area vs. ideal
    indicator: Slowing velocity in specific areas

  incident_correlation:
    measure: Incidents by component
    indicator: Same components causing issues

  developer_survey:
    questions:
      - "What slows you down most?"
      - "What areas need attention?"
      - "Where do you fear making changes?"

# Technical debt registry template
debt_items:
  - id: DEBT-001
    title: "Legacy authentication system"
    description: |
      Custom auth built in 2018. Missing MFA, poor session
      management, security vulnerabilities.
    category: Security
    severity: High
    impact: |
      - Security audit findings
      - Can't implement SSO
      - 2 incidents this quarter
    interest_rate: High (ongoing security risk)
    estimated_effort: 6 weeks
    owner: Platform Team
    created: 2021-03-15
    status: Planned Q4

  - id: DEBT-002
    title: "Monolithic order service"
    description: |
      500k LOC service handling orders, payments, inventory.
      Difficult to modify, test, deploy.
    category: Architecture
    severity: Medium
    impact: |
      - Deploy takes 2 hours
      - High blast radius
      - Team coupling
    interest_rate: Medium (slows all order features)
    estimated_effort: 3 months (decomposition)
    owner: Orders Squad
    created: 2021-06-01
    status: In Progress

debt_categories:
  architecture:
    - Monoliths that should be services
    - Tight coupling
    - Missing abstractions
    - Wrong technology choices

  code_quality:
    - Complex code
    - Missing tests
    - Poor error handling
    - Inconsistent patterns

  infrastructure:
    - Manual processes
    - Missing observability
    - Outdated infrastructure
    - Poor CI/CD

  dependencies:
    - Outdated libraries
    - Security vulnerabilities
    - Unsupported versions
    - Missing updates

  documentation:
    - Missing docs
    - Outdated docs
    - No runbooks
    - Tribal knowledge

prioritization_criteria:
  risk:
    weight: 30%
    factors:
      - Security vulnerabilities
      - Compliance issues
      - Business continuity

  velocity_impact:
    weight: 25%
    factors:
      - How much it slows development
      - How many teams affected
      - Frequency of interaction

  cost_to_fix:
    weight: 20%
    factors:
      - Effort to address
      - Risk of addressing
      - Dependencies

  strategic_alignment:
    weight: 15%
    factors:
      - Enables future work
      - Aligns with roadmap
      - Supports team goals

  opportunity:
    weight: 10%
    factors:
      - Already working in area
      - Team has context
      - Natural time to address

allocation_strategies:
  percentage_allocation:
    description: Reserve X% of capacity for debt
    typical_range: 15-25%
    pros: Predictable, sustainable
    cons: May not address urgent items fast enough

  debt_sprints:
    description: Dedicated sprints for debt
    frequency: Quarterly or as needed
    pros: Focused attention, larger items
    cons: Feature delivery pauses

  boy_scout_rule:
    description: Leave code better than you found it
    approach: Small improvements during feature work
    pros: Continuous improvement
    cons: Doesn't address large items

  combination:
    recommended: true
    approach:
      - 20% ongoing allocation
      - Boy scout for small items
      - Quarterly debt sprint for large items

communicating_debt:
  to_leadership:
    language:
      - Risk reduction
      - Velocity improvement
      - Cost avoidance
      - Competitive capability
    metrics:
      - Incident frequency
      - Deploy frequency
      - Time to deliver features
      - Engineer satisfaction

  example_framing:
    bad: "We need to refactor the authentication system"
    good: |
      "Our current auth system has 3 known security
      vulnerabilities and blocks SSO integration. Modernizing
      it reduces breach risk and enables the enterprise
      features customers are requesting. Estimated 6 weeks,
      ROI in 2 quarters through reduced incidents and
      enabled sales."

debt_paydown_execution:
  planning:
    - Define clear scope
    - Set measurable success criteria
    - Identify risks and mitigation
    - Plan for incremental delivery

  execution:
    - Prioritize highest-risk items
    - Deliver incrementally
    - Maintain current functionality
    - Test thoroughly

  validation:
    - Measure improvement
    - Validate assumptions
    - Gather feedback
    - Document learnings

debt_prevention:
  code_review:
    - Quality standards enforced
    - Debt explicitly discussed
    - Small, reviewable PRs

  architecture_review:
    - Design docs for significant work
    - Team review before implementation
    - Consider long-term implications

  definition_of_done:
    - Tests included
    - Documentation updated
    - Monitoring in place
    - No known debt introduced

  time_allocation:
    - Buffer for quality
    - Don't commit to 100% capacity
    - Account for maintenance

  retrospectives:
    - Discuss debt created
    - Identify patterns
    - Adjust practices