---
title: Technical Debt — Reference
---

# Technical Debt — Reference

The Technical Debt page tracks known quality compromises across all six project
domains — intentional shortcuts, design weaknesses, missing tests, and similar
issues that reduce codebase health but have been consciously deferred.

---

## Debt types

| Type | Examples |
|------|---------|
| **design** | Architectural decisions that should be revisited |
| **implementation** | Hacky or fragile code that works but shouldn't stay |
| **test** | Missing or incomplete test coverage |
| **docs** | Missing or outdated documentation |
| **dependencies** | Pinned old versions, unused packages, missing lockfiles |
| **performance** | Known bottlenecks not yet worth addressing |
| **security** | Hardcoded values, missing input validation, weak auth |
| **other** | Anything that doesn't fit the above |

---

## Severity levels

| Severity | Meaning |
|----------|---------|
| **critical** | Blocks release or poses an active risk |
| **high** | Should be resolved before the next major milestone |
| **medium** | Normal triage priority |
| **low** | Nice-to-fix; acceptable to defer indefinitely |

---

## Statuses

| Status | Meaning |
|--------|---------|
| **open** | Known and unaddressed |
| **in_progress** | Being actively worked on |
| **deferred** | Acknowledged but intentionally postponed |
| **resolved** | Fixed |
| **wont_fix** | Accepted as permanent — documented for future reference |

Items are sorted by status (open → in_progress → deferred → resolved → wont_fix)
then by severity (critical → high → medium → low) within each group.

---

## Filters

| Filter | Effect |
|--------|--------|
| **Status** | Multi-select |
| **Severity** | Multi-select |
| **Domain** | Multi-select |
| **Type** | Multi-select |

---

## Registering debt

Via MCP:

```
register_technical_debt(
  domain      = "custodian",
  title       = "Hard-coded API URL in data loaders",
  debt_type   = "implementation",
  severity    = "high",
  description = "All data loaders use http://127.0.0.1:8000 directly. Should read from an env var or config.",
  location    = "state-hub/dashboard/src/data/*.json.py",
  workstream_id = "<uuid>"   # optional
)
```

```
update_td_status(td_uuid="<uuid>", status="resolved")
```

---

## Human-readable IDs

Each debt item carries a human-readable ID in the form `TD-<DOMAIN>-NNN`
(e.g. `TD-CUST-001`). IDs are optional at creation and auto-assigned if omitted.
They appear in the table for easy reference in commit messages and comments.