# Trace UI workbench design

## Subject and audience

Subject: a single-session diagnosis trace audit workbench.

Audience: backend and AIOps engineers reviewing an MVP diagnosis run after a
demo, incident drill, or regression check.

Single job: turn one trace response into an inspectable ledger that exposes
agent flow, evidence, verifier judgement, and skill boundaries without reading
raw JSON first.

## Frontend approach

- Static `trace.html`, `trace.css`, and `trace.js`.
- No dependency on a package manager, bundler, external fonts, or remote icons.
- Fetches `/api/diagnosis/{sessionId}/trace` and renders client-side.
- Accepts `?sessionId=...` and keeps the loaded session id in the URL.

## Visual direction

Palette:

- `#111827` ink rail for the trace frame.
- `#f7f3ea` warm ledger surface.
- `#1f7a6b` evidence green.
- `#b5472f` rejection red.
- `#c58a19` warning amber.
- `#5b6472` operational gray.

Type:

- UI/body: `Inter, ui-sans-serif, system-ui`.
- Data and labels: `ui-monospace, SFMono-Regular, Consolas`.

Layout:

```text
+--------------------------------------------------------------------+
| Session id input | Load | status / verdict / counts strip          |
+------------------+----------------------+--------------------------+
| Agent trace rail | Evidence tool ledger | Inspector                |
| ordered steps    | filters + calls      | verifier + RAG + skill   |
+------------------+----------------------+--------------------------+
```

Signature element: a trace rail that treats each agent step as a ledger entry
with ordered markers, duration, token count, and expandable raw model excerpts.

## Data mapping

- `data.session`: summary strip, final answer, self-evaluation source.
- `data.steps`: ordered trace rail.
- `data.toolInvocations`: evidence ledger and selected tool inspector.
- `data.session.selfEvaluation.verifier_evaluation`: verdict, groundedness,
  facts table, and verifier `tool_trace_summary`.
- `data.toolInvocations[*].retrievalDetails`: RAG query transform, retrieval
  trace, context pack, rerank trace, and evidence blocks.
- `steps[*].modelOutput`: best-effort extraction of `selected_skill`.
- `steps[*].modelInput/modelOutput` and tool names: best-effort skill boundary
  checks for `read_skill`.

## Accessibility and states

- Keyboard-focusable controls.
- Loading, missing session id, API error, empty steps, empty tools, and missing
  verifier states.
- Responsive three-pane desktop layout that stacks on narrow screens.
- Respects `prefers-reduced-motion`.