Files
skills/public/engineering-technical-debt.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

564 lines
27 KiB
HTML
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>engineering-technical-debt</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/engineering-technical-debt.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/engineering-technical-debt">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/engineering-technical-debt.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>engineering-technical-debt</h1><p class="lede">Identifying, measuring, tracking, and managing technical debt strategically and systematically</p><h1>Technical Debt Management</h1>
<p><strong>Scope</strong>: Comprehensive guide to identifying, measuring, prioritizing, and paying down technical debt <strong>Lines</strong>: ~320 <strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<hr>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Evaluating whether to take on technical shortcuts</li><li>Prioritizing refactoring vs new features</li><li>Explaining tech debt costs to stakeholders</li><li>Planning debt paydown sprints</li><li>Auditing codebase health</li><li>Establishing tech debt policies</li><li>Preventing debt accumulation</li><li>Recovering from tech debt crisis</li></ul>
<h2>Core Concepts</h2>
<h3>Concept 1: What is Technical Debt?</h3>
<p><strong>Definition</strong>: Code shortcuts that speed up delivery but increase future maintenance costs</p>
<p><strong>Martin Fowler&#x27;s Quadrant</strong>:</p>
<pre><code> Reckless Prudent
Deliberate | &quot;We don&#x27;t have | &quot;We must ship now,
| time for | will refactor later&quot;
| design&quot; |
-------------|----------------|------------------
Inadvertent | &quot;What&#x27;s | &quot;Now we know how
| layering?&quot; | we should have
| | done it&quot;</code></pre>
<p><strong>Types of Tech Debt</strong>:</p>
<ul><li><strong>Code Debt</strong>: Poor code quality, duplication, smells</li><li><strong>Design Debt</strong>: Wrong abstractions, tight coupling</li><li><strong>Test Debt</strong>: Missing tests, brittle tests</li><li><strong>Documentation Debt</strong>: Outdated or missing docs</li><li><strong>Infrastructure Debt</strong>: Outdated dependencies, poor tooling</li><li><strong>Architecture Debt</strong>: Scaling issues, monolith problems</li></ul>
<hr>
<h3>Concept 2: Interest vs Principal</h3>
<p><strong>Like Financial Debt</strong>:</p>
<ul><li><strong>Principal</strong>: Cost to fix the issue</li><li><strong>Interest</strong>: Ongoing cost of living with it</li></ul>
<pre><code class="lang-python"># Example: Duplicated validation logic (Principal: 1 day to refactor)
# File 1
def create_user(email):
if &quot;@&quot; not in email: # Duplicated
raise ValueError(&quot;Invalid email&quot;)
# ... save user
# File 2
def update_user(email):
if &quot;@&quot; not in email: # Duplicated
raise ValueError(&quot;Invalid email&quot;)
# ... update user
# File 3
def invite_user(email):
if &quot;@&quot; not in email: # Duplicated
raise ValueError(&quot;Invalid email&quot;)
# ... send invite
# Interest paid:
# - Every bug fix needs 3 changes
# - Every validation enhancement needs 3 updates
# - Risk of inconsistency
# - Slows down all email-related features</code></pre>
<hr>
<h3>Concept 3: When to Take On Debt</h3>
<p><strong>Good Reasons</strong> (Deliberate, Prudent):</p>
<ul><li>MVP to validate market fit</li><li>Time-sensitive opportunity</li><li>Competitive pressure</li><li>Known paydown plan</li></ul>
<p><strong>Bad Reasons</strong> (Reckless):</p>
<ul><li>Laziness or lack of skill</li><li>&quot;We&#x27;ll never come back to this&quot;</li><li>No plan to pay down</li><li>Not understanding implications</li></ul>
<hr>
<h2>Patterns</h2>
<h3>Pattern 1: Debt Identification</h3>
<p><strong>Code Smells Checklist</strong>:</p>
<pre><code>[ ] Duplicated code (copy-paste)
[ ] Long methods (&gt; 30 lines)
[ ] Large classes (&gt; 500 lines)
[ ] Long parameter lists (&gt; 4 params)
[ ] Divergent change (class changes for multiple reasons)
[ ] Shotgun surgery (one change affects many classes)
[ ] Feature envy (method uses another class more than its own)
[ ] Data clumps (same group of data everywhere)
[ ] Primitive obsession (over-reliance on primitives)
[ ] Comments explaining complex code</code></pre>
<p><strong>Automated Detection</strong>:</p>
<pre><code class="lang-bash"># Python: Code complexity
radon cc src/ -a -nb # Cyclomatic complexity
radon mi src/ # Maintainability index
# JavaScript: ESLint complexity rules
eslint --max-complexity=10 src/
# Code duplication
jscpd src/ # Copy-paste detector
# Security debt
npm audit
pip-audit</code></pre>
<hr>
<h3>Pattern 2: Debt Measurement</h3>
<p><strong>Debt Score Formula</strong>:</p>
<pre><code>Debt Score = (Complexity × Impact × Frequency) / Ease of Fix
Complexity: 1-5 (how complex is the problem?)
Impact: 1-5 (how many people/systems affected?)
Frequency: 1-5 (how often is this code touched?)
Ease of Fix: 1-5 (how easy to fix?)</code></pre>
<p><strong>Example Scoring</strong>:</p>
<pre><code class="lang-python"># Debt Item: Duplicated email validation (3 places)
Complexity = 2 # Simple validation logic
Impact = 4 # Used in 10+ features
Frequency = 5 # Changed weekly
Ease of Fix = 4 # Easy - extract to function
Debt Score = (2 × 4 × 5) / 4 = 10
# Debt Item: Monolithic architecture
Complexity = 5 # Very complex to split
Impact = 5 # Affects entire system
Frequency = 3 # Changes monthly
Ease of Fix = 1 # Very difficult
Debt Score = (5 × 5 × 3) / 1 = 75 # High priority!</code></pre>
<hr>
<h3>Pattern 3: Debt Tracking</h3>
<p><strong>Debt Register</strong> (track in <code>TECH_DEBT.md</code>):</p>
<pre><code class="lang-markdown"># Technical Debt Register
## High Priority (Score &gt; 50)
### TD-001: Monolithic Database
- **Debt Score**: 75
- **Principal**: 4 weeks
- **Interest**: 1 day/week (slow queries, deployment bottleneck)
- **Paydown Plan**: Split into microservices over Q2
- **Status**: Planned
## Medium Priority (Score 20-50)
### TD-002: Missing Integration Tests
- **Debt Score**: 30
- **Principal**: 2 weeks
- **Interest**: 2 hours/week (manual testing)
- **Paydown Plan**: Add tests incrementally with each feature
- **Status**: In Progress
## Low Priority (Score &lt; 20)
### TD-003: Outdated Dependencies
- **Debt Score**: 12
- **Principal**: 1 day
- **Interest**: 30 min/month (security patches)
- **Paydown Plan**: Update in Q3 maintenance sprint
- **Status**: Backlog</code></pre>
<hr>
<h3>Pattern 4: Debt Paydown Strategies</h3>
<p><strong>Boy Scout Rule</strong>: Leave code better than you found it</p>
<pre><code class="lang-python"># Every PR: Small improvements
# Before
def process_user(email, name, age, address, phone): # Too many params
# ... 50 lines of code
# After (in PR for unrelated feature)
class UserData:
def __init__(self, email, name, age, address, phone):
self.email = email
self.name = name
# ...
def process_user(user_data: UserData): # Better!
# ... same logic</code></pre>
<p><strong>Debt Sprints</strong>: Dedicated time to pay down debt</p>
<pre><code>Sprint 10: Features (80%) + Debt (20%)
- Feature: User dashboard
- Debt: Extract shared validation logic
Sprint 11: Features (80%) + Debt (20%)
- Feature: Payment integration
- Debt: Add integration tests for auth
Sprint 15: Debt Sprint (100%)
- Upgrade all dependencies
- Refactor monolithic service
- Add missing documentation</code></pre>
<p><strong>Strangler Fig Pattern</strong>: Gradually replace old system</p>
<pre><code>1. Identify module to replace
2. Build new implementation alongside old
3. Route new requests to new code
4. Migrate existing data gradually
5. Remove old code when fully migrated
Example:
┌─────────────────┐
│ Old Auth System │ ←─┐
└─────────────────┘ │
├─ Route new users to new system
┌─────────────────┐ │ Migrate old users gradually
│ New Auth System │ ←─┘
└─────────────────┘</code></pre>
<hr>
<h3>Pattern 5: Preventing Debt</h3>
<p><strong>Definition of Done</strong> (include quality checks):</p>
<pre><code class="lang-markdown">## Definition of Done
Code Complete:
- [ ] Feature implemented
- [ ] Unit tests written (80%+ coverage)
- [ ] Integration tests added
- [ ] Documentation updated
- [ ] Code reviewed
- [ ] No TODO/FIXME comments (create tickets instead)
- [ ] No copy-paste code
- [ ] Cyclomatic complexity &lt; 10
- [ ] No security vulnerabilities</code></pre>
<p><strong>Pre-Commit Hooks</strong>:</p>
<pre><code class="lang-yaml"># .pre-commit-config.yaml
repos:
- repo: https://github.com/psf/black
hooks:
- id: black # Formatting
- repo: https://github.com/pycqa/flake8
hooks:
- id: flake8 # Linting
args: [--max-complexity=10]
- repo: https://github.com/pre-commit/mirrors-mypy
hooks:
- id: mypy # Type checking</code></pre>
<p><strong>Quality Gates in CI</strong>:</p>
<pre><code class="lang-yaml"># .github/workflows/quality.yml
- name: Check code quality
run: |
radon cc src/ -a -nb --total-average-threshold=B
radon mi src/ --min=C
- name: Check test coverage
run: |
pytest --cov=src --cov-fail-under=80
- name: Check for code duplication
run: |
jscpd src/ --threshold 5 # Fail if &gt; 5% duplication</code></pre>
<hr>
<h2>Debt Communication</h2>
<h3>Explaining to Stakeholders</h3>
<p><strong>Avoid</strong>: &quot;We have technical debt&quot; (vague, no context)</p>
<p><strong>Better</strong>: Use analogies and business impact</p>
<pre><code>&quot;Our authentication system is like a house built without a foundation.
It works today, but:
- Every new feature takes 2x longer to build
- Security fixes require changes in 5 different places
- We have 3 critical bugs per month due to inconsistency
Investment: 2 weeks to refactor
Payoff: 50% faster feature development, 90% fewer auth bugs
ROI: Pays for itself in 2 months&quot;</code></pre>
<p><strong>Debt Dashboard</strong> (visualize for stakeholders):</p>
<pre><code>Tech Debt Metrics Dashboard
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Total Debt: 12 weeks
Interest Cost: 8 hours/week
High Priority Debt: [██████----] 60%
Test Coverage: [████------] 45%
Code Duplication: [██████----] 15%
Complexity: [████████--] 80%
Trend: ↑ Increasing (action needed!)</code></pre>
<hr>
<h2>Best Practices</h2>
<h3>Debt Management Guidelines</h3>
<p><strong>Do&#x27;s</strong>:</p>
<ul><li>Track debt explicitly (don&#x27;t hide it)</li><li>Measure debt objectively</li><li>Pay down incrementally</li><li>Prevent new debt</li><li>Communicate impact to stakeholders</li><li>Schedule regular debt sprints</li><li>Use automated tools</li></ul>
<p><strong>Don&#x27;ts</strong>:</p>
<ul><li>Don&#x27;t ignore growing debt</li><li>Don&#x27;t pay all debt at once (balance with features)</li><li>Don&#x27;t blame individuals</li><li>Don&#x27;t take on debt without plan</li><li>Don&#x27;t use &quot;tech debt&quot; as excuse for poor work</li><li>Don&#x27;t let debt compound</li></ul>
<hr>
<h2>Anti-Patterns</h2>
<h3>Common Debt Management Mistakes</h3>
<pre><code>❌ &quot;We&#x27;ll fix it later&quot; (Never happens)
→ Fix now or create explicit paydown plan
❌ Ignoring debt until crisis
→ Track and pay down incrementally
❌ Only paying principal, ignoring interest
→ Prioritize high-interest debt first
❌ 100% features, 0% debt paydown
→ Allocate 20% of sprint to debt
❌ Rewriting from scratch
→ Refactor incrementally (strangler fig)
❌ Not measuring debt
→ Quantify to prioritize effectively
❌ Debt as excuse for poor quality
→ Deliberate, prudent debt only</code></pre>
<hr>
<h2>Decision Framework</h2>
<h3>Should We Take On This Debt?</h3>
<pre><code>IF time_pressure AND short_term_need AND have_paydown_plan:
TAKE_ON_DEBT
DOCUMENT(why, when_fix, cost)
SCHEDULE_PAYDOWN
ELSE:
DO_IT_RIGHT</code></pre>
<p><strong>Example Decision Matrix</strong>: | Situation | Take Debt? | Condition | |-----------|------------|-----------| | MVP launch | ✅ Yes | Must have paydown plan | | Competitive threat | ✅ Yes | Document &amp; schedule fix | | Learning new tech | ✅ Yes | First time doing X | | Lack of skill | ❌ No | Learn or ask for help | | Laziness | ❌ No | Do it right | | No plan to fix | ❌ No | Schedule paydown or don&#x27;t ship |</p>
<hr>
<h2>Code Examples</h2>
<h3>Before (High Debt):</h3>
<pre><code class="lang-python"># Duplicated validation everywhere
def create_user(email, password):
if not email or &quot;@&quot; not in email:
raise ValueError(&quot;Invalid email&quot;)
if len(password) &lt; 8:
raise ValueError(&quot;Password too short&quot;)
# ... create user
def update_email(user_id, email):
if not email or &quot;@&quot; not in email: # Duplicated!
raise ValueError(&quot;Invalid email&quot;)
# ... update email
def send_invite(email):
if not email or &quot;@&quot; not in email: # Duplicated!
raise ValueError(&quot;Invalid email&quot;)
# ... send invite</code></pre>
<h3>After (Debt Paid):</h3>
<pre><code class="lang-python"># Extracted validation (DRY)
class EmailValidator:
@staticmethod
def validate(email: str) -&gt; None:
if not email or &quot;@&quot; not in email:
raise ValueError(&quot;Invalid email&quot;)
class PasswordValidator:
@staticmethod
def validate(password: str) -&gt; None:
if len(password) &lt; 8:
raise ValueError(&quot;Password too short&quot;)
def create_user(email, password):
EmailValidator.validate(email)
PasswordValidator.validate(password)
# ... create user
def update_email(user_id, email):
EmailValidator.validate(email)
# ... update email
def send_invite(email):
EmailValidator.validate(email)
# ... send invite</code></pre>
<hr>
<h2>Related Skills</h2>
<ul><li><strong>engineering-refactoring-patterns</strong>: Techniques for paying down debt</li><li><strong>engineering-code-quality</strong>: Preventing debt through quality</li><li><strong>engineering-code-review</strong>: Catching debt in reviews</li><li><strong>engineering-test-driven-development</strong>: Preventing test debt</li><li><strong>engineering-continuous-integration</strong>: Automated debt detection</li></ul>
<hr>
<h2>References</h2>
<ul><li><a href="https://martinfowler.com/bliki/TechnicalDebt.html">Technical Debt by Martin Fowler</a></li><li><a href="https://www.construx.com/blog/managing-technical-debt/">Managing Technical Debt by Steve McConnell</a></li><li><a href="https://stackoverflow.blog/2023/02/27/the-human-cost-of-tech-debt/">The Human Cost of Tech Debt</a></li><li><a href="https://martinfowler.com/bliki/TechnicalDebtQuadrant.html">Tech Debt Quadrant</a></li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/engineering-technical-debt.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>