state-hub/dashboard/src/techdept.md

---
title: Technical Debt
---

```js
import {API, POLL_HEAVY, apiFetch, pollDelay, waitForVisible} from "./components/config.js";
```

```js
const tdState = (async function*() {
  let failures = 0;
  while (true) {
    let data = [], ok = false;
    try {
      const [rt, rw, rto, rr] = await Promise.all([
        apiFetch("/technical-debt/"),
        apiFetch("/workplans/"),
        apiFetch("/topics/"),
        apiFetch("/repos/"),
      ]);
      ok = rt.ok && rw.ok && rto.ok && rr.ok;
      if (ok) {
        const [tdList, wsList, topicList, repoList] = await Promise.all([rt.json(), rw.json(), rto.json(), rr.json()]);
        const topicMap = Object.fromEntries(topicList.map(t => [t.id, t]));
        const repoMap  = Object.fromEntries(repoList.map(r => [r.id, r]));
        const wsMap    = Object.fromEntries(wsList.map(w => [w.id, {
          ...w, domain: repoMap[w.repo_id]?.domain_slug ?? topicMap[w.topic_id]?.domain_slug ?? "unknown",
        }]));
        data = tdList.map(t => ({
          ...t,
          workstream_title: wsMap[t.workstream_id]?.title ?? null,
        })).sort((a, b) => {
          const sv = {critical: 0, high: 1, medium: 2, low: 3};
          const st = {open: 0, in_progress: 1, deferred: 2, resolved: 3, wont_fix: 4};
          const sd = (st[a.status] ?? 9) - (st[b.status] ?? 9);
          return sd !== 0 ? sd : (sv[a.severity] ?? 9) - (sv[b.severity] ?? 9);
        });
      }
    } catch {}
    failures = ok ? 0 : failures + 1;
    yield {data, ok, ts: new Date()};
    await waitForVisible(pollDelay({ok, base: POLL_HEAVY, failures}));
  }
})();
```

```js
const data = tdState.data ?? [];
const _ok  = tdState.ok   ?? false;
const _ts  = tdState.ts;
```

```js
import {MultiSelect} from "./components/multiselect.js";

const STATUSES   = ["open", "in_progress", "resolved", "deferred", "wont_fix"];
const SEVERITIES = ["critical", "high", "medium", "low"];
const _domainsResp = await fetch(`${API}/domains/?status=active`).catch(() => null);
const DOMAINS = _domainsResp?.ok
  ? (await _domainsResp.json()).map(d => d.slug)
  : ["custodian", "railiance", "markitect", "coulomb_social", "personhood", "foerster_capabilities"];
const DEBT_TYPES = ["design", "implementation", "test", "docs", "dependencies", "performance", "security", "other"];

const _filtersForm = Inputs.form(
  {
    status:    MultiSelect(STATUSES,   {label: "Status",    placeholder: "All statuses"}),
    severity:  MultiSelect(SEVERITIES, {label: "Severity",  placeholder: "All severities"}),
    domain:    MultiSelect(DOMAINS,    {label: "Domain",    placeholder: "All domains"}),
    debt_type: MultiSelect(DEBT_TYPES, {label: "Type",      placeholder: "All types"}),
  },
  {
    template: ({status, severity, domain, debt_type}) => html`<div class="filter-bar">
      ${status}${severity}${domain}${debt_type}
    </div>`,
  }
);
```

```js
const filters = Generators.input(_filtersForm);
```

```js
const filtered = data.filter(t =>
  (filters.status.length    === 0 || filters.status.includes(t.status)) &&
  (filters.severity.length  === 0 || filters.severity.includes(t.severity)) &&
  (filters.domain.length    === 0 || filters.domain.includes(t.domain_slug)) &&
  (filters.debt_type.length === 0 || filters.debt_type.includes(t.debt_type))
);
```

# Technical Debt

```js
import {injectTocTop}    from "./components/toc-sidebar.js";
import {withDocHelp}     from "./components/doc-overlay.js";
import {openEntityModal} from "./components/entity-modal.js";

// ── KPI sidebar ───────────────────────────────────────────────────────────────
const _open     = data.filter(t => t.status === "open" || t.status === "in_progress");
const _critical = data.filter(t => t.severity === "critical" && t.status === "open");
const _high     = data.filter(t => t.severity === "high"     && t.status === "open");
const _resolved = data.filter(t => t.status === "resolved");
const _total    = data.filter(t => t.status !== "wont_fix").length;
const _resolvedPct = _total > 0 ? Math.round(_resolved.length / _total * 100) : 0;

const _kpiBox = html`<div class="kpi-infobox">
  <div class="kpi-infobox-title">Tech Debt</div>
  <div class="kpi-row">
    <span class="kpi-row-label">open</span>
    <div class="kpi-row-right"><div class="kpi-row-value">${_open.length}</div></div>
  </div>
  <div class="kpi-row">
    <span class="kpi-row-label">critical</span>
    <div class="kpi-row-right">
      <div class="kpi-row-value" style="color:${_critical.length > 0 ? '#dc2626' : 'inherit'}">${_critical.length}</div>
    </div>
  </div>
  <div class="kpi-row">
    <span class="kpi-row-label">high</span>
    <div class="kpi-row-right">
      <div class="kpi-row-value" style="color:${_high.length > 0 ? '#d97706' : 'inherit'}">${_high.length}</div>
    </div>
  </div>
  <div class="kpi-row" style="border-top:1px solid var(--theme-foreground-faint,#eee)">
    <span class="kpi-row-label">resolved</span>
    <div class="kpi-row-right">
      <div class="kpi-row-value">${_resolved.length}</div>
      <div class="kpi-row-sub">${_resolvedPct}% of total</div>
    </div>
  </div>
</div>`;

// ── Live indicator ─────────────────────────────────────────────────────────────
const _liveEl = html`<div class="live-indicator">
  <span style="color:${_ok ? 'var(--theme-foreground-focus)' : 'red'}">●</span>
  ${_ok
    ? `Live · updated ${_ts?.toLocaleTimeString()}`
    : html`<span style="color:red">Offline — run: <code>make api</code></span>`}
</div>`;
withDocHelp(_liveEl, "/docs/live-data");

const _h1 = document.querySelector("#observablehq-main h1");
if (_h1) { _h1.style.position = "relative"; withDocHelp(_h1, "/docs/debt"); }

injectTocTop("td-kpi-box", _kpiBox);
injectTocTop("live-indicator", _liveEl);
```

## By Type & Severity

```js
import * as Plot from "npm:@observablehq/plot";

const SEVERITY_COLOR = {critical: "#dc2626", high: "#ea580c", medium: "#3b82f6", low: "#94a3b8"};
const TYPE_COLOR = {
  design: "#8b5cf6", implementation: "#3b82f6", test: "#f59e0b",
  docs: "#10b981", dependencies: "#6366f1", performance: "#ec4899",
  security: "#dc2626", other: "#94a3b8",
};

const bySeverity = SEVERITIES
  .map(s => ({severity: s, count: filtered.filter(t => t.severity === s && t.status !== "resolved" && t.status !== "wont_fix").length}))
  .filter(d => d.count > 0);

const byType = DEBT_TYPES
  .map(t => ({type: t, count: filtered.filter(d => d.debt_type === t).length}))
  .filter(d => d.count > 0);

if (filtered.length === 0) {
  display(html`<p class="dim">No technical debt items match the current filter.</p>`);
} else {
  display(html`<div class="chart-row">
    ${bySeverity.length > 0 ? Plot.plot({
      marks: [
        Plot.barX(bySeverity, {y: "severity", x: "count", fill: d => SEVERITY_COLOR[d.severity] ?? "#94a3b8", tip: true}),
        Plot.ruleX([0]),
      ],
      marginLeft: 80, width: 300, title: "Open by severity",
    }) : ""}
    ${byType.length > 0 ? Plot.plot({
      marks: [
        Plot.barX(byType, {y: "type", x: "count", fill: d => TYPE_COLOR[d.type] ?? "#94a3b8", tip: true}),
        Plot.ruleX([0]),
      ],
      marginLeft: 110, width: 360, title: "By type",
    }) : ""}
  </div>`);
}
```

## Critical & High

```js
const _urgent = filtered.filter(t => (t.severity === "critical" || t.severity === "high") && t.status === "open");

if (_urgent.length === 0) {
  display(html`<p class="dim">No critical or high severity open items in current filter. ✓</p>`);
} else {
  display(html`<div class="td-list">${_urgent.map(t => html`
    <div class="td-item td-sev-${t.severity} entity-row"
         onclick=${() => openEntityModal(t, "td")}
         title="Click to view full details">
      <div class="td-item-header">
        ${t.td_id ? html`<span class="td-ref">${t.td_id}</span>` : ""}
        <span class="td-sev-badge td-sev-${t.severity}">${t.severity}</span>
        <span class="td-type-badge">${t.debt_type}</span>
        <span class="td-domain">${t.domain}</span>
        ${t.workstream_title ? html`<span class="td-ws" title=${t.workstream_title}>${t.workstream_title}</span>` : ""}
      </div>
      <div class="td-title">${t.title}</div>
      ${t.description ? html`<div class="td-desc">${t.description.slice(0, 220)}${t.description.length > 220 ? " …" : ""}</div>` : ""}
      ${t.location    ? html`<div class="td-location"><code>${t.location}</code></div>` : ""}
    </div>
  `)}</div>`);
}
```

## All Technical Debt

```js
display(_filtersForm);
display(html`<p><strong>${filtered.length}</strong> items shown.</p>`);

display(html`<div class="td-list">${filtered.map(t => html`
  <div class="td-item td-status-${t.status} entity-row"
       onclick=${() => openEntityModal(t, "td")}
       title="Click to view full details">
    <div class="td-item-header">
      ${t.td_id ? html`<span class="td-ref">${t.td_id}</span>` : ""}
      <span class="td-sev-badge td-sev-${t.severity}">${t.severity}</span>
      <span class="td-type-badge">${t.debt_type}</span>
      <span class="td-badge td-badge-${t.status}">${t.status.replace("_", " ")}</span>
      <span class="td-domain">${t.domain}</span>
      ${t.workstream_title ? html`<span class="td-ws" title=${t.workstream_title}>${t.workstream_title}</span>` : ""}
    </div>
    <div class="td-title">${t.title}</div>
    ${t.description ? html`<div class="td-desc">${t.description.slice(0, 220)}${t.description.length > 220 ? " …" : ""}</div>` : ""}
    ${t.location    ? html`<div class="td-location"><code>${t.location}</code></div>` : ""}
  </div>
`)}
</div>`);
```

<style>
/* ── Live indicator ───────────────────────────────────────────────────────── */
.live-indicator { font-size: 0.8rem; color: gray; position: relative; padding: 0.55rem 1.8rem 0.55rem 0.7rem; margin-bottom: 0.75rem; }

/* ── KPI infobox ──────────────────────────────────────────────────────────── */
.kpi-row { display: flex; justify-content: space-between; align-items: center; gap: 1rem; padding: 0.3rem 0; border-top: 1px solid var(--theme-foreground-faint, #eee); }
.kpi-row:first-of-type { border-top: none; }
.kpi-row-label { font-size: 0.8rem; color: var(--theme-foreground-muted, #666); }
.kpi-row-right { text-align: right; }
.kpi-row-value { font-size: 1.25rem; font-weight: 700; font-variant-numeric: tabular-nums; line-height: 1.1; }
.kpi-row-sub { font-size: 0.68rem; color: var(--theme-foreground-faint, #aaa); }

/* ── Charts ───────────────────────────────────────────────────────────────── */
.chart-row { display: flex; flex-wrap: wrap; gap: 1.5rem; align-items: flex-start; }

/* ── Filters ──────────────────────────────────────────────────────────────── */

/* ── TD list ──────────────────────────────────────────────────────────────── */
.td-list { display: flex; flex-direction: column; gap: 0.5rem; }
.td-item { border-left: 3px solid #94a3b8; border-radius: 0 6px 6px 0; background: var(--theme-background-alt); padding: 0.65rem 0.9rem; }
.td-item.entity-row { cursor: pointer; transition: filter 0.1s; }
.td-item.entity-row:hover { filter: brightness(0.97); }
.td-sev-critical { border-left-color: #dc2626; }
.td-sev-high     { border-left-color: #ea580c; }
.td-sev-medium   { border-left-color: #3b82f6; }
.td-sev-low      { border-left-color: #94a3b8; }
.td-status-resolved { opacity: 0.55; }
.td-status-wont_fix { opacity: 0.4; }
.td-item-header { display: flex; flex-wrap: wrap; align-items: center; gap: 0.4rem; margin-bottom: 0.3rem; }
.td-ref { font-family: monospace; font-size: 0.72rem; color: var(--theme-foreground-muted); background: var(--theme-background); border: 1px solid var(--theme-foreground-faint, #ddd); border-radius: 4px; padding: 0.05rem 0.35rem; }
.td-sev-badge { display: inline-block; padding: 0.1rem 0.45rem; border-radius: 10px; font-size: 0.7rem; font-weight: 700; text-transform: uppercase; }
.td-sev-critical { background: #fee2e2; color: #991b1b; border-left-color: #dc2626; }
.td-sev-high     { background: #ffedd5; color: #9a3412; border-left-color: #ea580c; }
.td-sev-medium   { background: #dbeafe; color: #1e40af; border-left-color: #3b82f6; }
.td-sev-low      { background: #f1f5f9; color: #475569; border-left-color: #94a3b8; }
.td-type-badge { display: inline-block; padding: 0.1rem 0.4rem; border-radius: 4px; font-size: 0.68rem; font-weight: 600; font-family: monospace; background: #f1f5f9; color: #475569; }
.td-badge { display: inline-block; padding: 0.1rem 0.45rem; border-radius: 10px; font-size: 0.7rem; font-weight: 500; }
.td-badge-open        { background: #dbeafe; color: #1e40af; }
.td-badge-in_progress { background: #fef3c7; color: #92400e; }
.td-badge-resolved    { background: #dcfce7; color: #166534; }
.td-badge-deferred    { background: #f1f5f9; color: #64748b; }
.td-badge-wont_fix    { background: #f3f4f6; color: #9ca3af; }
.td-domain { color: var(--theme-foreground-muted); font-size: 0.75rem; }
.td-ws     { font-style: italic; color: var(--theme-foreground-faint); font-size: 0.72rem; }
.td-title  { font-weight: 600; font-size: 0.95rem; margin-bottom: 0.15rem; }
.td-desc   { font-size: 0.82rem; color: var(--theme-foreground-muted); line-height: 1.45; }
.td-location { font-size: 0.75rem; color: var(--theme-foreground-faint); margin-top: 0.2rem; }

/* ── Utility ──────────────────────────────────────────────────────────────── */
.dim { color: gray; font-style: italic; }
</style>