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>
This commit is contained in:
91
state-hub/dashboard/src/docs/debt.md
Normal file
91
state-hub/dashboard/src/docs/debt.md
Normal file
@@ -0,0 +1,91 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user