130 lines
7.1 KiB
Markdown
130 lines
7.1 KiB
Markdown
# 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.*
|