Files

tegwick 235355eb58 feat(dashboard): nav restructure, full context-help coverage, 11 new ref docs

Navigation:
- New order: Overview · Todo · Domains · Repos · Workstreams (collapsible,
  open:false, with atomic sub-entries: Decisions, Tasks, Debt, Extends,
  Dependencies) · Contributions · SBOM · Progress · Reference (collapsible)
- Reference section gains path:/reference landing page; all 18 doc pages
  listed in nav (alphabetical) and in reference.md table

New pages:
- todo.md — Internal / Ecosystem / Third-party todo classification
- dependencies.md — dependency edge table derived from state/summary
- reference.md — Reference landing page with full doc index

New reference doc pages (11):
  contributions, debt, dependencies, domains, extensions, overview,
  repos, tasks, todo + reference (meta) already added previously

doc-overlay.js — lazy bubblehelp tooltip:
- _titleCache Map + _fetchDocTitle(docPath): on first hover of any ?
  button, fetches the target doc page, parses <h1>, sets btn.title
- Native browser tooltip appears exactly on the ? circle on subsequent hover

Context-help wired on all 14 dashboard pages:
- h1 withDocHelp added to: index, todo, domains, repos, tasks, techdept,
  extensions, dependencies (contributions/workstreams/decisions/sbom/
  progress/reference were already wired)
- domains.md + repos.md: added missing withDocHelp import and live-data link
- tasks/techdept/extensions: removed duplicate _h1 const that caused
  SyntaxError: Identifier '_h1' has already been declared

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-01 23:46:26 +01:00

2.5 KiB

Raw Blame History

title

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.

2.5 KiB Raw Blame History