# 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.*