experiment: separate ui mock reference from deferred backlog

docs/ui-mock-reference.md

@@ -0,0 +1,62 @@
+# UI Mock Reference — Confidence Engine
+
+> Created by Experiment 31. This document contains practical reference information for working with investigation mock fixtures. It is separate from deferred UX planning which lives in `docs/archive/deferred-ux-backlog.md`. Do not load the deferred backlog unless a named past UX idea is being reviewed.
+
+---
+
+## Available Mock Scenarios
+
+The following scenarios are defined as e2e fixtures and can be replayed for UI development and testing:
+
+| Fixture | Purpose |
+| --- | --- |
+| Happy path (multi-turn) | General UI flow |
+| Contradiction | Validate contradiction reasoning |
+| Comparison | Compare two options |
+| Definition | Clarify ambiguous terms |
+| Diagnosis | Fault-finding flow |
+| Prioritisation | Ranking and trade-offs |
+| Revision replay | Editing earlier evidence and rebuilding reasoning |
+| No-question (needs more evidence) | Non-terminal pause |
+| Genuine completion | Investigation finished |
+| Long investigation (10–15 turns) | History, scrolling, collapsing |
+| Slow provider | Loading experience |
+| Provider error | Error handling |
+| Malformed response | Robustness and recovery |
+
+---
+
+## Where Fixture Data Lives
+
+- **Fixture definitions**: `tests/e2e/fixtures/investigation-scenarios.js` — shared scenario content (central statements, answer sequences, expected headings).
+- **Mock client**: `lib/mocks/confidence-engine/mock-client.js` — interceptor + scenario replay logic.
+- **Test harness**: Components under `tests/e2e/specs/` drive each scenario through the UI.
+- **Scenario selector**: Set `NEXT_PUBLIC_CONFIDENCE_ENGINE_MOCK_SCENARIO` env var in `components/scenario-form.jsx`.
+
+---
+
+## When to Use Each Scenario
+
+| Scenario | When to use it |
+| --- | --- |
+| Happy path (multi-turn) | General UI flow testing; verifying turn-by-turn progression and history updates. |
+| Contradiction | Testing contradiction detection, user-facing contradiction messaging, reasoning display. |
+| Comparison | Two-option comparison flows; validating side-by-side or prioritised presentation. |
+| Definition | Clarifying ambiguous terms; testing definition-mode responses. |
+| Diagnosis | Fault-finding / troubleshooting flows. |
+| Prioritisation | Ranking and trade-off scenarios. |
+| Revision replay | Testing evidence revision, graph rebuild, and reasoning chain updates. |
+| No-question (needs more evidence) | Non-terminal pause states — "no further question available" UI. |
+| Genuine completion | Investigation completion messages, confidence threshold UI. |
+| Long investigation (10–15 turns) | History scrolling, collapsing, pacing, memory behaviour over extended sessions. |
+| Slow provider | Loading spinners, feedback messages during delayed responses (30–60s). |
+| Provider error | Connection failure handling, error state UI recovery. |
+| Malformed response | Invalid or partial JSON — robustness and resilience testing. |
+
+---
+
+## Important Notes
+
+- These mock scenarios are **fixture-driven only**. Their behaviour does not represent live-engine capabilities unless the corresponding engine features are implemented and enabled.
+- The fixture content (central statements, answer sequences) is fictional data. Do not treat mock evidence as real reasoning output.
+- For scenario names usable in `NEXT_PUBLIC_CONFIDENCE_ENGINE_MOCK_SCENARIO`, consult `tests/e2e/fixtures/investigation-scenarios.js` directly.