How It Works

Tracking debt as explicit architectural decisions:

# Technical Debt Registry (maintained as a structured document or in a tool)

DEBT-001:
    Title: Shared-table multi-tenancy
    Introduced: 2023-01-15 (v1.0 launch)
    Decision: All tenant data in shared tables, filtered by tenant_id
    Reason: Speed to market; single tenant at launch
    Interest: Each new tenant increases query complexity; data isolation is per-query not per-schema
    Trigger for repayment: First customer requiring data residency OR >100 tenants
    Estimated repayment cost: 3-4 engineers for 3 months
    Current status: ACTIVE — 40 tenants, no residency requirement yet

DEBT-007:
    Title: No retry logic in payment webhook handler
    Introduced: 2023-06-20
    Decision: Webhook failures are logged but not retried
    Reason: Retry logic was out of scope for the sprint
    Interest: Lost payment notifications require manual reconciliation
    Trigger for repayment: First missed payment notification in production
    Estimated repayment cost: 2 engineers for 2 weeks
    Current status: OVERDUE — 3 incidents in the past month

Measuring the impact on velocity:

# Lines changed per feature — tracked over releases
Feature: Add Klarna payment method
    Files changed: 47
    Lines changed: 1,240
    Expected for this complexity: 8 files, 200 lines

Feature: Add Apple Pay
    Files changed: 52
    Lines changed: 1,380

# Conclusion: payment method additions are 6x more expensive than they should be
# Root cause: payment provider logic not abstracted behind an interface
# Debt classification: Inadvertent/Reckless (no factory, no adapter pattern)
# Repayment: Extract PaymentGateway interface and adapters for all current providers
# Estimated: 2 engineers, 3 weeks
# ROI: break even after 1.5 additional payment methods