Technical Debt Inventory & Paydown Plan

Template Overview

Every fast-growing software company accumulates technical debt. Taking on strategic debt to validate an early market hypothesis is a normal commercial trade-off. However, when technical debt is ignored, architectural ‘interest’ compounds relentlessly: builds slow down, code becomes fragile, refactoring becomes terrifying, and engineering velocity collapses.

Managing technical debt requires treating it like financial debt: auditing the inventory, calculating recurring interest payments, prioritizing high-leverage paydown items, and negotiating dedicated engineering capacity in sprint planning.

This template provides an engineering-grade Technical Debt Inventory: classifying debt archetypes, calculating recurring interest taxes, ranking refactoring ROI, and planning structured paydown allocations.

Markdown Template Structure

Copy the block below or click Download .md File to add this template directly to your personal vault:

---
title: "Technical Debt Inventory: [Repository / Subsystem]"
date: [YYYY-MM-DD]
repository_name: "avocado-web / desktop-runtime"
lead_architect: "[[Chief Systems Architect]]"
total_debt_items_cataloged: 8
estimated_monthly_interest_tax: "42 Engineering Hours / Month"
paydown_sprint_allocation: "20% of Ongoing Sprint Velocity"
tags: [technical-debt, refactoring, architecture, engineering, code-health]
---

# Technical Debt Inventory: [Repository / Subsystem] — [YYYY-MM-DD]

## 1. Executive Debt Health & Velocity Impact
- **Current State Assessment:** Core application architecture is healthy, but build automation and CI/CD pipelines carry high friction taxes that slow down release verification.
- **Monthly Interest Tax:** The team loses approximately 42 engineering hours each month to flaky test reruns, manual deployment checks, and duplicated template data structures.

## 2. Technical Debt Catalog & Interest Taxation
| Debt ID | Subsystem / Module | Debt Description & Root Cause | Monthly Interest Tax | Paydown Effort | Paydown ROI | Status |
| :--- | :--- | :--- | :--- | :--- | :--- | :--- |
| **DEBT-01** | CI/CD Build Pipeline | Cloud test VMs run slow and time out on macOS integration tests | 18 hrs / mo | 16 hrs (Setup Mac test runner) | **Very High (11x)** | 🟡 Scheduled |
| **DEBT-02** | Template Generation | Duplicate dictionary definitions between script and content collections | 12 hrs / mo | 8 hrs (Consolidate shared schema) | **High (9x)** | 🟡 In Progress |
| **DEBT-03** | Audio Engine Callbacks | Hardcoded 256-sample buffer size risks frame drops under thermal load | 8 hrs / mo | 12 hrs (Dynamic 1024 buffer) | **High (7x)** | 🟢 Resolved (PR #830) |
| **DEBT-04** | CSS Design Tokens | Hardcoded hex color codes in older migration pages | 4 hrs / mo | 6 hrs (Replace with `--color` tokens) | **Medium (5x)** | 🔵 Backlog |

## 3. High-Leverage Paydown Deep-Dive: DEBT-01 (Dedicated Mac Test Runner)
- **Problem:** Running macOS audio regression tests on cloud virtual machines introduces 45-minute wait times and frequent false-positive timeouts.
- **Paydown Strategy:** Provision an on-premise Apple Silicon M2 Mac Mini hardware runner connected to GitHub Actions, reducing test runs to 3 minutes.
- **Payoff:** Saves 18 developer hours monthly and allows true hardware-level CoreAudio regression testing.

## 4. Negotiated Sprint Capacity Allocation
> [!IMPORTANT] Engineering Capacity Agreement
> Product and Engineering leadership agreed to dedicate **20% of story points in every two-week sprint** exclusively to technical debt paydown and architectural hardening.

## 5. Paydown Commitments for Next Sprint
- [ ] [[Systems Eng]] Configure on-premise Mac mini test runner for CI/CD pipeline.
- [ ] [[Frontend Eng]] Audit and refactor hardcoded color values across migration pages.
- [ ] Review technical debt inventory during monthly engineering retrospective.

Filled Real-World Example

Here is a realistic example demonstrating how this template captures actual deliberations:

---
title: "Tech Debt: October 2026 Audit"
date: 2026-10-06
repository_name: "avocado-web"
estimated_monthly_interest_tax: "42 Hours"
tags: [technical-debt, refactoring]
---

# Tech Debt: October 2026 Audit — October 6, 2026

## 1. High-Priority Paydown
Resolved DEBT-03 (CoreAudio ring buffer sizing). Increased buffer to 1024 samples with zero frame drops.

## 2. Next Paydown
Configure dedicated hardware test runner to eliminate CI/CD cloud timeouts.

When to Use and When to Avoid

When to Use

• Use during quarterly technical debt audits and engineering architecture reviews.
• Use to quantify recurring time taxes and calculate return on investment for proposed refactorings.
• Use to secure dedicated engineering capacity allocation (e.g. 20%) from product leadership.

When to Avoid

• Avoid using as an excuse to rewrite functioning code merely for aesthetic personal preferences.
• Avoid using for user-facing product feature requirements (use [[product-requirements-doc-prd]]).

On-Device AI Integration

Capture technical debt audits with Oyma on macOS:

Analyze the engineering technical debt review meeting transcript:
1. Synthesize the repository name, lead architect, and estimated monthly engineering interest tax.
2. Build the technical debt catalog table ranking debt items by monthly time tax, effort, and paydown ROI.
3. Detail a deep-dive implementation plan for the highest-leverage technical debt paydown item.
4. Record the negotiated sprint capacity allocation percentage and immediate paydown sprint commitments.
Output in disciplined, engineering-grade CommonMark format.

Your internal code health audits and technical debt backlogs remain completely private on your Mac.