updated context documents

2026-08-04 17:33:51 +01:00
parent c3faf53823
commit 437152086b
4 changed files with 452 additions and 0 deletions
@@ -72,3 +72,21 @@ Previous cases may suggest where to investigate, but they must never determine
 the outcome of a new case.

 Every case begins with no accepted evidence from previous cases.
+
+## Product Principle: TL;DR First
+
+The Confidence Workspace is not a document viewer or chat transcript. It is an active investigation workspace.
+
+At any point, the interface should allow a user returning after seconds, minutes or hours to understand where they are within a few seconds.
+
+The workspace should always answer:
+
+1. What is the situation?
+2. What have we established?
+3. What is the single most important thing to determine next?
+4. Why does that matter?
+5. How close are we to having sufficient confidence?
+
+The interface should minimise cognitive load by presenting the current state first and allowing progressively deeper exploration only when requested.
+
+The engine may contain hundreds of reasoning nodes; the user should only see the information required to take the next meaningful action.
@@ -135,3 +135,45 @@ Avoid:
 - dashboard-style density.

 The next question should be the strongest visual element.
+
+## TL;DR Workspace Rules
+
+The newest state is the most important state.
+
+The primary focus of every screen should be the user's next action, not the history of how they arrived there.
+
+### Information hierarchy
+
+1. Current investigation
+2. Why this matters
+3. Response
+4. Current understanding
+5. Investigation history
+6. Original situation
+7. Developer details
+
+### Progressive disclosure
+
+Show only the information needed for the current decision.
+
+Everything else should be collapsible or secondary.
+
+### Cognitive load
+
+The user should never need to scan an entire page to discover:
+
+- what is happening
+- what they need to do next
+- why they are being asked
+
+These should always be immediately visible.
+
+### Investigation history
+
+History exists to provide confidence and traceability, not to compete with the current investigation.
+
+History should remain collapsed unless the user chooses to inspect previous reasoning.
+
+### Original situation
+
+Once an investigation has started, the original scenario becomes reference material rather than the primary focus.
@@ -121,3 +121,5 @@ At the end of a task, normally report only:
 Stop after reporting. Do not begin the next task automatically.

 When a task is interrupted by output limits, resume with a narrowly scoped repair prompt rather than restating the entire original brief.
+
+User interfaces communicate reasoning, not implementation. If a piece of information exists only because the engine tracks it internally (graph nodes, unresolved counts, edge totals, confidence scores), it should remain in Developer Details unless it directly helps the user make their next decision.
@@ -0,0 +1,390 @@
+## Mock fixtures to note for later reasoning refinement
+
+Keep a backlog of these mock scenarios so you can continue developing the UX independently of Ollama:
+
+| 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                           |
+
+# Confidence Engine UI Roadmap
+
+The reasoning engine has reached a point where the next priority is not adding more capability, but improving the experience of using what already exists. The goal is to make the investigation feel coherent, understandable and satisfying while keeping the underlying reasoning visible enough for development without exposing unnecessary complexity to end users.
+
+---
+
+# Phase 1 – Complete the Core Investigation Experience
+
+## 1. Investigation History
+
+Finish the investigation history so it reads like an investigation notebook rather than a chat log.
+
+Each completed question should record:
+
+- The question asked
+- The user's answer
+- The resulting understanding (optional where appropriate)
+
+Example:
+
+```text
+✓ Were both figures measured over the same period?
+
+Answer
+Yes. Both covered the same quarter.
+
+Outcome
+The figures can now be compared directly.
+```
+
+This should become the permanent chronological record of the investigation.
+
+## 2. Current Understanding
+
+Replace "What we've established" with something closer to:
+
+Current understanding
+Confidence so far
+
+The purpose is to show how uncertainty is reducing over time.
+
+Example:
+
+```text
+Current understanding
+
+✓ Same reporting period confirmed
+
+✓ Comparable baselines confirmed
+
+• Complaint rate still requires investigation
+```
+
+This card should update cumulatively after every answer.
+
+## 3. Current Investigation
+
+This becomes the primary focus of the interface.
+
+Keep it deliberately simple.
+
+```text
+Current investigation
+
+Question
+
+...
+
+Why this matters
+
+...
+```
+
+Nothing more.
+
+The user should always understand:
+
+- what they're answering
+- why it matters
+
+## 4. Loading Experience
+
+Replace generic loading messages with investigation-specific feedback.
+
+Examples:
+
+```text
+Reviewing your answer...
+
+Checking what changes...
+
+Updating our understanding...
+
+Choosing the next question...
+```
+
+Avoid fake progress bars or percentages.
+
+# Phase 2 – UX Polish
+
+### Animated progression
+
+Instead of updating the page instantly:
+
+```text
+Answer submitted
+
+↓
+
+History updates
+
+↓
+
+Current understanding updates
+
+↓
+
+Next investigation appears
+```
+
+Small animations should reinforce the feeling of progressing through an investigation.
+
+### Progressive completion
+
+Completed investigation steps should gradually become:
+
+```
+✓ Same reporting period
+
+✓ Comparable baselines
+
+✓ Complaint rate
+
+► Reporting consistency
+```
+
+### Collapsible history
+
+Once the investigation becomes long:
+
+```
+Investigation history (8)
+
+▼
+
+Allow older questions to collapse.
+```
+
+### Better ending states
+
+Avoid generic messages such as:
+
+```
+No further questions.
+```
+
+Instead distinguish between outcomes.
+
+For example:
+
+```
+Current evidence has taken us as far as it can.
+
+Further investigation requires additional evidence.
+```
+
+or
+
+```
+The investigation is complete.
+
+Current confidence is sufficient to make a decision.
+```
+
+Different endings communicate different reasoning outcomes.
+
+## Phase 3 – Developer Experience
+
+Developer Details are becoming crowded.
+
+Split them into logical sections:
+
+```
+Developer Details
+
+Overview
+
+Graph
+
+Diagnostics
+
+Raw JSON
+
+Mock Data
+```
+
+This keeps debugging information available without overwhelming the interface.
+
+## Phase 4 – Mock Scenario Library
+
+Before returning to reasoning refinement, build a richer set of mock scenarios.
+
+These allow UI work to continue independently of the reasoning engine.
+
+#### Existing
+
+- Happy path
+- Complete investigation
+- Error state
+- No question available
+
+#### Required
+
+Contradiction
+
+Two observations conflict.
+
+Example:
+
+```
+Observation A
+
+Observation B
+
+↓
+
+Contradiction detected
+
+↓
+
+Question
+Comparison
+```
+
+Compare two options.
+
+#### Examples:
+
+- House A vs House B
+- Product A vs Product B
+
+#### Definition
+
+Clarify an ambiguous term.
+
+#### Example:
+
+"What do you mean by..."
+
+#### Diagnosis
+
+Fault finding and troubleshooting.
+
+#### Prioritisation
+
+Several competing options requiring selection.
+
+#### Revision
+
+Support changing an earlier answer.
+
+Example:
+
+```
+Q1
+
+A1
+
+Q2
+
+A2
+
+User edits A1
+
+↓
+
+Reasoning rebuilds
+```
+
+Even if replay isn't implemented yet, mock the behaviour.
+
+### Long investigation
+
+10–15 question investigation.
+
+Used for:
+
+- scrolling
+- collapsing history
+- pacing
+
+### Slow provider
+
+Simulate very slow model responses (30–60 seconds).
+
+Used for refining loading behaviour.
+
+### Provider error
+
+Connection failure.
+
+### Malformed provider response
+
+Invalid or partial JSON.
+
+Useful for resilience testing.
+
+## Backlog
+
+Reasoning Replay
+
+Create a replay mode for completed investigations.
+
+Example:
+
+```
+Statement
+
+↓
+
+Question 1
+
+↓
+
+Answer
+
+↓
+
+Graph updates
+
+↓
+
+Question 2
+
+↓
+
+Answer
+
+↓
+
+Graph updates
+
+↓
+
+...
+```
+
+Uses include:
+
+- demonstrations
+- debugging
+- explaining the reasoning process
+- validating graph updates
+
+This reinforces the principle:
+
+    The graph remembers. The conversation explains.
+
+## Deliberately Out of Scope
+
+The following should wait until repeated real-world testing reveals genuine reasoning issues:
+
+- Reasoning algorithms
+- Graph architecture
+- Confidence calculation
+- Decomposition improvements
+- Reasoning pattern expansion
+- Investigation strategy changes
+
+The current focus is making the investigation experience clear, understandable and enjoyable before expanding the reasoning engine further.