confidence-engine/docs/v0.7-user-workspace-ux-first-pass.md

v0.7 UX First Pass — User-Focused Reasoning Workspace

UX Problem

The current interface exposes the reasoning engine's graph structure directly to users. It presents:

• Raw node-grouped tables with status/confidence badges
• Diagnostic metadata (model name, prompt version, validation status)
• Graph update change details (resolved nodes, affected nodes, proposal JSON)
• A bare "Waiting for model response..." placeholder with no elapsed time or rotating status

This is useful as a developer/debug view but difficult to understand for non-technical users. The next question is visually buried under the graph tables, and there is no clear feedback during slow LLM analysis or update operations.

Design Goals

• Calmer default view: Present scenario, understanding, focus, next question, and progress as a sequence of clean cards
• Preserve full debug access: All existing graph, diagnostics, and update history components remain available behind a collapsed disclosure
• Clear slow-operation feedback: Animated spinner, elapsed time, rotating plain-language status messages during analysis and update operations
• Professional visual tone: Neutral colours, generous whitespace, restrained borders, no gradients or glassmorphism

Main Workspace Structure

The ReasoningWorkspace component (components/reasoning-workspace.jsx) renders the result area. When a successful start analysis completes, it shows:

1. Your situation — Central statement from situationGraph.centralStatement, displayed in a white card
2. Current understanding — The API's currentSummary text in a second white card
3. What we are working out — The active unknown label, its description ("Why it matters"), and a plain-language status badge (e.g., "Under investigation")
4. Next question — The largest visual element: green-bordered card with bold heading and prominent question text in text-xl font-weight-semibold
5. Progress — A single inline bar showing resolved count + remaining unknown count (no percentage)
6. Answer form — Visible only when a selected question exists; textarea + "Update situation" button, disabled during update loading
7. Developer details — Collapsible <details> element with full SituationGraphView, GraphUpdateView, and DiagnosticsView inside; closed by default

When analysis completes without producing a graph:

• A yellow warning card states the outcome plainly
• Error messages remain in red cards above all content

When there is no next question:

• A calm gray card says "There is no next question at the moment." with a contextual elaboration derived from noQuestionReason when available
• No broken-looking empty areas appear

Loading-State Behaviour

Initial analysis (start request)

A blue-bordered card appears with:

• Spinner — CSS-only spinning ring (@keyframes spin)
• Heading: "Working through your situation"
• Rotating status text (based on elapsed seconds):
  • 0–10s: "Reading your situation"
  • 10–25s: "Building a structured understanding"
  • 25–45s: "Identifying what is known and still unclear"
  • 45+s: "Selecting the next useful question"
• Elapsed time: "This has been running for Xs."
• Reassuring copy (shown after 30s): "This can take around a minute with the current local model."

Answer update (update request)

Same card format, different status text pool:

• 0–10s: "Considering your answer"
• 10–25s: "Updating the situation"
• 25–45s: "Checking what changed"
• 45+s: "Choosing the next question"

Duplicate submit prevention

Both "Analyse" and "Update situation" buttons are disabled while their respective status / updateStatus is "loading". The answer textarea also disables during update loading.

Debug View Preservation

All existing components are preserved inside the collapsed "Developer details" <details> element:

• SituationGraphView — Full node-grouped graph with badges, active unknown highlighting, newly surfaced markers, and raw JSON toggle
• GraphUpdateView — Update history (resolved unknowns, newly surfaced unknowns, affected nodes, proposal details)
• DiagnosticsView — Model name, provider, prompt version, duration, validation status, node/edge counts

These are only accessible by expanding the disclosure. Raw node IDs do not appear in any user-facing card text.

Deliberate Exclusions (for this pass)

• Spider/dag graph rendering
• Persistence or session handling
• Navigation or routing changes
• Accounts or authentication
• Export functionality
• Dark mode
• Radical input page redesign
• Backend code changes (APIs, routes, logic, prompts, schemas)
• Reasoning test modifications
• New component library additions

Remaining UX Limitations

1. Multi-turn not implemented — The workspace currently reflects the one-update prototype limitation. A multi-turn version would need persistent state management between turns.
2. Timer is client-side only — Elapsed time starts when loading begins but no backend stage telemetry is exposed yet, so rotating messages are honest approximations only.
3. No skeleton/loading shimmer — The spinner card replaces content entirely during loading rather than showing a layout-aware skeleton. A skeleton approach would be a future enhancement.
4. Loading overlay does not persist across route changes — No persistence layer means refresh loses state. This is intentional for the prototype scope.
5. No visual distinction between "idle" and "success" empty states — Both render similarly when no answer is typed. A small hint like "Type an answer to continue" could be added later.
6. Progress count uses resolved/remaining labels only — No percentage or bar despite having the data, per constraint. This is intentional; we avoid false precision in a prototype context.

Files Changed

File	Change
components/reasoning-workspace.jsx	New — main workspace component with cards, loading feedback, developer details disclosure
components/scenario-form.jsx	Refactored to use ReasoningWorkspace for result rendering; removed inline answer form/debug panels from render
app/globals.css	Added @keyframes spin animation definition
tests/ui/scenario-form.test.jsx	20 new tests for ReasoningWorkspace rendering, loading states, error states, no-question states, debug view preservation

Test Results

• All 48 UI tests pass (28 existing + 20 new)
• ESLint: no warnings or errors
• Next.js build: clean, no new route entries or compilation issues

Manual UI Notes

A single manual check was not performed in this pass. The next step for verification is:

1. Run npm run dev
2. Submit a scenario to an available local LLM endpoint
3. Confirm the initial loading card shows rotating status messages
4. Confirm the result renders as a clean sequence of cards with "Next question" as the strongest visual element
5. Expand "Developer details" and confirm graph/diagnostics/updates are preserved
6. Submit an answer and confirm update loading feedback appears
7. Confirm no raw node IDs appear outside the developer section

---

This is a first-pass UX improvement only. Reasoning logic, API contracts, schemas, and tests remain unchanged.