confidence-engine/docs/archive/experiments/pre-RTO/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

## Loading Feedback Refinement

The loading state was tightened for clarity:

- Reassurance message threshold moved from 30 s to 45 s to avoid premature reassurance.
- Elapsed time displayed in seconds during both initial analysis and answer update.
- Rotating status messages continue per the original pools, changing based on elapsed seconds only.

## Progress Card — Unexplained Counts Replaced

The standalone "X remaining" text was replaced with a `Reasoning progress` card:

- **Areas under investigation** — Plain-language statement of how many areas remain (e.g., "We have identified 1 area that still needs investigation.").
- **Current focus** — The active unknown label, shown in plain language.
- **Why this matters** — The active unknown's description, when available.
- Fallback text ("There is no active area of investigation at the moment.") when there is no active unknown and no remaining areas.

Words such as "unknown nodes", "unresolved nodes", "remaining graph items", and "candidate count" are intentionally avoided in user-facing copy.

## Current Understanding Wording

The `Current understanding` card continues to display whatever text `currentSummary` provides from the API. When `currentSummary` is absent, a calm fallback message appears: "We have started to separate what is known from what still needs checking." Technical graph counts (node types, edge totals) are no longer constructed or displayed in user-facing sections — they are only available inside the collapsed Developer details disclosure.

## Developer-Detail Boundary

- **User-facing cards** show: situation summary, current understanding, reasoning progress with active focus, and next question — all without raw IDs, node kinds, or internal enum names.
- **Developer details** (collapsed `<details>` element) preserves the full SituationGraphView (node groups, badges, edge info), GraphUpdateView (update history, proposal details), and DiagnosticsView (model name, prompt version, validation status, node/edge counts).
- No user-facing card renders raw node IDs or technical graph metadata.

## 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` | Loading feedback refinement (45 s threshold); ProgressSummary → ReasoningProgress card; CurrentUnderstanding simplified; DeveloperDetails boundary clarified |
| `tests/ui/scenario-form.test.jsx` | Added 8 new focused UI tests covering progress card, reasoning focus, loading behavior, and technical-data isolation; removed outdated "remaining" count assertion |
| `docs/v0.7-user-workspace-ux-first-pass.md` | Added sections for loading feedback refinement, progress-card replacement, current-understanding wording, developer-detail boundary |

## Test Results

- All 58 UI tests pass (50 existing + 8 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.*