CodeClarityLab / DEBT
← Home ← Glossary ← Codex
DEBT Sections
↓ Whitepaper (PDF)
⚖ CC BY 4.0
An open standard from CodeClarityLab

CVSS scores attackers.
OWASP scores attacks.
DEBT scores what code concepts cost developers.

A four-axis risk profile for the cost a programming concept imposes on the developer who uses it. The four kinds of debt your code concepts owe.

Debt is not failure. It's the cost of using a system with tradeoffs. Using == is cognitive debt. Picking microservices early is structural debt. Skipping linting is operational debt. None of these are moral failures — they're engineering decisions with cost profiles. DEBT helps you see the bill before you sign.
Read the spec → Why this design

The format

debt(d3/e2/b5/t7)
Four axes, each 1–9. Letter prefix tells you which axis is which without a legend. 0 means the axis genuinely doesn't apply.

That string is the entire format. Compact enough to fit inline next to a concept name, structured enough to query and filter, self-documenting through letter prefixes. Full format spec →

The four axes

Each measures one independent kind of debt. They're independent on purpose — if you can predict one from another, the score is wasting a slot. Each axis carries its own colour throughout the pillar so you can spot which kind is which on sight.

d
Detectability
Operational debt
How invisible misuse is to your safety net. Higher score = your linter, type checker, and review process won't catch it before production.
e
Effort
Remediation debt
Work required to fix once spotted. One-line patch on one end; multi-quarter architectural rewrite on the other.
b
Burden
Structural debt
Long-term weight of choosing wrong. Two flavours: decay (slowly poisons the codebase over time) and reach (load-bearing across the system, system-wide blast radius). Both score on the same axis.
t
Trap
Cognitive debt
How counter-intuitive the correct behaviour is. The gap between what a smart developer would assume and what actually happens.

Four kinds of debt — the framing

Every line of code you write incurs at least one form of debt. Not abstract debt — literal cost someone has to pay later. The DEBT axes give that cost a structure.

Operational debt
You owe your safety net. Skipping linting or static analysis is debt against your future self — the tooling that would have caught the bug isn't there.
Remediation debt
You owe your time. A bug that takes a quarter to fix is debt against every other thing the team could have shipped that quarter.
Structural debt
You owe the team. Picking microservices for a 5-person startup is debt against every developer who joins after you, paying interest on the architectural choice for years.
Cognitive debt
You owe your mental model. Using == in PHP without internalising type juggling is debt against your understanding of what == means.

DEBT scores all four kinds at once. Not as a single number — as a profile. A concept with high cognitive debt and low structural debt is fundamentally different from one with low cognitive debt and high structural debt, even if they "feel equally bad."

What's in this pillar

01 · Reference
Spec
The formal definition. Format, axes, anchor examples per axis, scoring procedure, JSON schema, FAQ.
02 · Background
Reasoning
Why these four axes. Why not five. What was rejected. The story behind the design choices.
03 · Visual
Design & badges
Visual identity, badge SVGs, rendering rules, embed snippets. How DEBT looks in the wild.

Use it on your project

DEBT is published under CC BY 4.0. You can use it on your own glossary, codebase, or documentation, with attribution to CodeClarityLab.

The format debt(d_/e_/b_/t_) is intentionally distinctive so a score is recognisable in the wild and traceable back to the canonical rubric. Forks, adaptations, and corrections welcome — please link back to codeclaritylab.com/debt as the upstream source.