confidence-engine/docs/design-evolution-log.md

# Design Evolution Log

A chronological record of why significant design decisions were made. This is NOT a changelog. It records the product's evolution of thinking.

This document records discoveries, not decisions. Every entry represents our best understanding at that point in time and may later be superseded by a better model.

---

## Phase 1

Simple conversational investigation

Question → Answer interaction.

Purpose:
Prove the reasoning loop.

Learning:
Conversation alone does not provide sufficient context during longer investigations.

---

## Phase 2

Persistent investigation notebook

Added:

- current understanding
- original situation
- investigation history

Learning:
Users need persistent context rather than remembering previous answers.

---

## Phase 3

Document workspace

Created a coherent workspace with:

- investigation status
- current investigation
- response
- understanding
- investigation map placeholder
- situation
- history

Learning:
The interface became usable but still behaved like a document rather than a workspace.

---

## Phase 4 (Current Exploration)

Facilitated Investigation Workshop

Status:
Experimental.

Hypothesis:

The Confidence Engine is not:

- a chatbot
- a dashboard
- a form

It is a facilitated investigation workspace.

The interface should resemble the environment in which structured thinking happens.

Record discoveries rather than conclusions.

Leave room for future phases.

---

## Phase 4 — Guiding Principles

The Confidence Engine is a workspace, not a document.

People think in multiple directions simultaneously.

Useful context should be visible together.

The interface should favour thinking over scrolling.

The workspace should feel like a large desk or workshop rather than a narrow report.

The engine facilitates thinking.

The user contributes evidence.

The workspace captures shared understanding.

### Experiment 01 — Wider canvas

Hypothesis:
The document-like feeling is caused partly by the narrow outer container.

Change:
Increase the available desktop workspace width without rearranging any components.

Result:
Confirmed.

Learning:
Increasing the outer workspace width reduced the narrow-document feeling and made better use of large displays.

Unexpected learning:
Width alone did not create a workshop. The wider canvas exposed that the interface still behaves as a collection of independent cards, with supporting artefacts unsure how to use the available space.

Decision:
Keep the wider desktop canvas.

Next question:
Can grouping the interface into cognitive work zones make the wider canvas feel like a coherent investigation surface?

### Experiment 02 — Cognitive work zones

Hypothesis:
A workspace organised around what the investigator is doing will feel more coherent than one organised around equal cards or equal columns.

Result:
Partially confirmed.

Learning:

The workspace feels more coherent when organised into cognitive work zones rather than a simple document stack.

However, another distinction emerged that is more important than the zones themselves.

The interface naturally separates into two different modes:

• the active conversation between investigator and facilitator

and

• the shared workspace describing the current understanding.

Unexpected learning:

History feels incorrect when treated as reference information.

History is actually the continuation of the investigator's conversation.

Every response immediately becomes history.

The notebook should therefore grow naturally from the Response area.

The Investigation Status card currently competes with the Current Investigation card.

The current question is the primary focus.

Status is supporting context.

Decision:

Keep the cognitive-zone concept.

Refine the zones around conversational flow instead of card grouping.

Next question:
Can the workspace clearly separate conversation from shared understanding?

### Experiment 03 — Conversation versus Workspace

Hypothesis

Investigators think in two simultaneous modes.

Mode 1:
The conversation.

Question
↓

Response
↓

History

Mode 2:
The shared workspace.

Status

Understanding

Situation

Map

Separating these should make the interface feel more like a facilitated investigation than a collection of cards.

Evaluation:
Partially confirmed.

Learning:

The workspace feels more coherent when organised into cognitive zones rather than a simple document stack.

However, another distinction emerged that is more important than the zones themselves.

The interface naturally separates into two different modes:

• the active conversation between investigator and facilitator

and

• the shared workspace describing the current understanding.

Unexpected learning:

History feels incorrect when treated as reference information.

History is actually the continuation of the investigator's conversation.

Every response immediately becomes history.

The notebook should therefore grow naturally from the Response area.

The Investigation Status card currently competes with the Current Investigation card.

The current question is the primary focus.

Status is supporting context.

Decision:

Keep the cognitive-zone concept.

Refine the zones around conversational flow instead of card grouping.

Next question:
Can the workspace clearly separate conversation from shared understanding?

### Experiment 04 — Facilitated Workshop Introduction

Hypothesis

Beginning with a facilitator-style introduction will create more confidence than presenting an empty workspace.

Questions

- Does the interface feel more welcoming?
- Does reducing the visual weight of the textarea improve the first experience?
- Does separating "starting" from "investigating" feel natural?
- Does the transition into the investigation workspace feel meaningful?

Status:
Experimental.

Result:
Partially confirmed.

Learning:

The facilitator introduction reduced the intimidation of the first screen.

Replacing the empty landing page with a guided introduction improved the emotional tone.

However, stacking the introduction above the input still gives the introduction excessive visual prominence.

Repeat users may not want to repeatedly read the same introduction.

Orientation should remain available without dominating the workflow.

Decision:

Keep the introduction concept but change its spatial relationship to the workspace — move it from above to beside, making it optional rather than mandatory.

Next question:
Does a horizontal facilitator/workspace layout feel more natural?

### Experiment 05 — Facilitator Panel and Adaptive Landing Workspace

Hypothesis

Placing the facilitator beside the working area will feel more like entering a facilitated workshop than stacking instructional content above the workspace.

Allowing the user to dismiss the facilitator will reduce friction for returning users while preserving onboarding for new users.

Questions

- Does a horizontal facilitator/workspace layout feel more natural?
- Does the user's eye move naturally from facilitator to workspace?
- Does the workspace become the primary focus?
- Does "Don't show again" feel preferable to automatically hiding the introduction?
- Should the facilitator panel become an optional workspace companion rather than mandatory onboarding?

Status:
Completed.

Findings:

- A horizontal facilitator/workspace arrangement feels more natural than stacked onboarding.
- The workspace becomes the visual destination rather than the introduction.
- User-controlled dismissal is preferable to automatic hiding.
- The facilitator feels useful but visually too passive.
- Remaining issues are now visual hierarchy rather than layout architecture.

### Experiment 06 — Focused Investigation

Hypothesis

The interface should gently guide attention towards the current task without hiding supporting information.

Reducing competition between panels may improve concentration more than introducing additional colour or decoration.

Questions

- Does visual emphasis naturally guide the eye?
- Can supporting panels become quieter without disappearing?
- Does the investigation question become the obvious focal point?
- Does the workspace feel calmer?
- Are we approaching a professional investigation environment?

Status:
Closed.

## Result

Partially confirmed.

## What did we learn?

- Stronger visual hierarchy can direct attention without rearranging the interface.
- The facilitator briefing became easier to distinguish.
- Colour and tint improved separation only modestly.
- Meaning must not depend on colour.
- Areas and intent should remain distinguishable through structure, spacing, typography, borders, shape and placement.
- The initial textarea still implies that the user should provide a detailed report.
- The size of an input communicates the amount of information expected.

## Decision

Retain the useful hierarchy refinements provisionally.

Do not increase reliance on colour.

Defer dark mode and broader palette work.

The next experiment should test whether a smaller starting input better communicates that the user only needs to provide an initial observation.

Do not rewrite previous experiments.

---

### Experiment 07 — Lightweight Starting Observation

#### Hypothesis

A smaller initial input will make beginning an investigation feel easier and will communicate that the engine needs only a concise observation rather than a complete analysis.

#### Questions

- Does the input feel like a conversation starter rather than a report form?
- Is three to four visible lines sufficient?
- Does the facilitator panel and input area feel better balanced?
- Does the user understand that further detail will be gathered through questions?
- Does reducing the input height make the Analyse action easier to notice?

#### Evaluation

Pending visual review.

#### Result

Confirmed.

Four visible rows better communicates a starting observation than six.

Input size communicates expected effort.

"What have you noticed?" reinforces observational thinking.

Users are encouraged to begin rather than compose.

The facilitator and workspace now feel more balanced.

This interaction principle should continue throughout the investigation rather than existing only on the landing page.

#### Decision

Retain the smaller landing input.

Proceed to investigate consistency between the landing experience and investigation responses.

---

### Experiment 09 — Investigation Rhythm

#### Result

Partially confirmed.

#### What did we learn?

- Moving History directly beneath Response improves the sense of conversational continuity.
- The sequence Question → Response → History is cognitively coherent.
- History behaves like the growing notebook of the investigation, not general reference material.
- Allowing History to span the full workspace breaks the wider spatial model.
- Situation and Investigation Map should remain stable supporting artefacts rather than moving down as the notebook grows.
- The conversation needs a dedicated vertical lane.

#### Decision

Keep History directly connected to Response.

Refine the desktop workspace into a stable conversation lane and a stable supporting lane.

Do not rewrite previous experiments.

---

### Experiment 08 — Consistent Investigation Responses

#### Hypothesis

Every answer given during an investigation should feel like an observation, not a report.

The response component should therefore communicate the same expected effort as the initial scenario input.

#### Questions

- Does a smaller response area reduce perceived effort?
- Does the investigation feel more conversational?
- Does consistency improve confidence?
- Does the workspace become visually calmer?
- Does the current investigation remain the dominant focus?

#### Result

Confirmed.

Consistent interaction patterns reduce cognitive effort.

Users should not have to learn different behaviours between the landing page and investigation.

Smaller response areas reinforce concise observations.

The engine appears more conversational when each answer feels lightweight.

Consistency is becoming a stronger design tool than decoration.

#### Decision

Retain consistent input sizing across both contexts.

---

### Experiment 10 — Stable Conversation Column

#### Hypothesis

A persistent two-thirds conversation column beside a one-third supporting column will allow the investigation notebook to grow without moving the shared reference artefacts.

#### Questions

- Does the left column feel like one continuous investigation?
- Does History grow naturally beneath Response?
- Do Situation and Investigation Map remain easy to reference?
- Does the interface feel spatially stable as turns accumulate?
- Does showing full question text improve readability now that sufficient width exists?

#### Evaluation

Visual review completed.

#### Status

Closed.

## Result

Partially confirmed.

## What did we learn?

- The investigation workspace is beginning to feel like a genuine facilitated investigation rather than a document.
- The two-column workspace (conversation on the left, reference material on the right) is proving to be a stronger mental model than previous layouts.
- Keeping Situation and Investigation Map fixed while History grows vertically feels more natural.
- The investigation question, response and history now read as one continuous conversation.
- Developer Details have become extremely valuable.
- The graph produced by the reasoning engine is far richer than previously realised. The graph now contains structured concepts including:

  - observations
  - unknowns
  - assumptions
  - relationships
  - metrics
  - state

This suggests the UI should increasingly become a human-friendly projection of the graph rather than inventing separate state.

The current "Investigation in progress" panel exposes developer-oriented statistics (nodes, edges, unknowns etc.) which are useful during development but are not the most helpful representation for an end user.

---

## Emerging Direction — Graph as Source of Truth

The reasoning graph is becoming the shared source of truth for multiple UI views.

Different interfaces may project the same graph for different audiences:

- Version A — compact technical progress;
- Version B — detailed graph inspection;
- Version C — user-facing facilitator view;
- Developer Details — complete diagnostics;
- Investigation Map — future spatial projection;
- Current Question — active uncertainty projection.

The UI should not maintain separate invented summaries where the graph already contains the underlying information.

This is an emerging direction, not a final architecture decision.

---

## Emerging Direction — Facilitator Translation Layer

> The UI should progressively become a translation layer over the reasoning graph rather than maintaining separate duplicated summaries. Internal graph concepts should remain available for developers, while end users see a facilitator-style explanation of what is currently understood and what remains uncertain.

The current technical progress panel (nodes, edges, unknowns, assumptions) exposes developer-oriented statistics. These are valuable during development but not the most helpful representation for an end user.

The next direction is to explore presenting the same underlying graph data as a facilitator's notebook — what is known, what remains uncertain, and a quiet summary of the reasoning state underneath.

---

### Experiment 11 — Facilitator Progress Panel (Version B)

#### Hypothesis

The same underlying reasoning graph can be presented in a much more human-friendly way without changing the reasoning engine, API contracts, or graph generation.

A facilitator-style panel should communicate:

- what is known (resolved nodes and observations)
- what remains uncertain (unresolved unknowns and assumptions)
- a quiet summary of the reasoning state underneath

#### Questions

- Can the same graph data be translated into a facilitator-style view that end users understand more naturally?
- Does separating "known" from "still investigating" reduce cognitive load compared to node/edge counts?
- Is a quiet reasoning summary sufficient, or does it need more context?
- Does the translation-layer principle hold — presenting the graph as a notebook rather than raw data?

#### Result

Partially confirmed.

#### What did we learn?

- Version B proved that the reasoning graph contains substantially more useful information than Version A exposes.
- The graph already contains observations, unknowns, assumptions, metrics, relationships and state.
- The graph is rich enough to support multiple UI projections.
- Exposing the graph almost verbatim overwhelms the user.
- Technical categories are useful for development but do not directly communicate investigation progress.
- The user needs a translation of the graph rather than a graph browser.
- Developer Details should remain the place for complete technical inspection.
- A user-facing view needs filtering, prioritisation, deduplication and clear epistemic labels.

#### Decision

Keep Version A and Version B available for comparison.

Proceed with a Version C facilitator view built from the same graph.

---

### Experiment 12 — Facilitator View (Version C)

#### Hypothesis

The existing reasoning graph can be deterministically translated into a concise facilitator view that helps the user understand:

- what is currently known;
- what remains uncertain;
- what may explain the situation;
- why the investigation is continuing.

#### Questions

- Can the graph produce a useful human-facing summary without another LLM call?
- Can observations, unknowns and assumptions be clearly distinguished?
- Can duplicate or low-value graph content be filtered reliably?
- Does a concise projection improve understanding without exposing implementation detail?
- Does the panel remain useful across mocks and live Ollama output?
- Can the same view work during early, middle and terminal investigation states?

#### Evaluation

Completed. Visual and live-data review performed.

#### Result

Confirmed.

#### What did we learn?

- The reasoning graph already contains all the information needed for a useful human-facing summary — no additional LLM calls are required.
- Routing by semantic role (observation, question, explanation) rather than graph kind produces a more natural user experience.
- Filtering scaffolding content (scenario summaries, system/tool references, metric object descriptions, process labels) is essential to keep the view focused on findings.
- Deduplication of near-duplicate observations reduces noise without losing information.
- Epistemic clarity matters — resolved unknowns become factual observations and should be classified as known rather than still-under-investigation.
- The panel works across all investigation phases (early, active, terminal).

#### Decision

Close Experiment 12 as confirmed. Proceed to refine the translation through semantic classification in the next iteration.

---

### Experiment 13 — Semantic Facilitator Translation

#### Hypothesis

Improving the deterministic projection from graph semantics to user-facing language — by classifying nodes by *meaning* rather than *graph kind*, suppressing scaffolding, merging duplicates, and preferring concrete observations — produces a significantly better facilitator view without changing the reasoning engine, prompts, graph generation, or any external contracts.

#### Questions

- Does semantic role classification (observation vs question vs explanation) route content more naturally than graph-kind classification?
- Does scaffolding suppression remove visual noise that previously dominated derived summaries?
- Does deduplication reduce redundant items that express the same observation under slightly different wording?
- Do concrete observations appear before abstract labels in ranked output?
- Does the view remain robust when consumed by the existing panel component (investigation-summary-panel-v3) without any changes to that component?

#### Evaluation

Completed. Tests: 37 scenarios passing across filtering, classification, deduplication, ranking, section framing, mock-data integration, and edge cases.

#### Result

Confirmed.

#### What did we learn?

- Semantic role routing outperforms kind-based routing: a node with `kind: "state"` that contains concrete data (e.g., "Revenue increased 12%") is more useful as an observation than a state description.
- Scaffolding suppression works best when applied early — filtering at the semantic classification stage prevents structural glue from contaminating any section.
- Three-tier filtering is effective: scaffolding patterns (highest priority), internal vocabulary (medium), then technical summary patterns (lowest).
- Deduplication by normalised text removes meaningful noise. When "Revenue increased 12%" and "Current revenue is 12% higher" express the same observation, keeping one reduces confusion without losing information.
- Resolved unknowns and assumptions are factual answers to previously unanswered questions — they should appear in the known section with an epistemic label ("Not yet established" / "To be tested") if their status hasn't been explicitly set.
- The translation adapter is the right place for this work: it is a single deterministic function, testable in isolation, and its output contracts are stable.

#### Decision

Keep the semantic projection approach. The facilitator view now routes by meaning, suppresses structural noise, deduplicates observations, and prefers concrete findings. Experiment 13 is closed.

---

## Emerging Direction

The first UX experiments focused on workspace structure.

The next series will focus on investigation rhythm.

Future experiments should explore:

- how conversations unfold
- how understanding evolves
- how transitions feel
- how confidence is gradually built

The objective is no longer to arrange cards.

The objective is to make the investigation feel like a natural facilitated conversation.

---

## Current Open Questions

The following are active explorations rather than decisions.

- What is the right metaphor for the product?
- Should the workspace resemble a facilitated workshop?
- How should decomposition be represented?
- What information belongs in shared understanding?
- What should the Investigation Map eventually become?
- How should wide thinking be reflected in the interface?

## Backlog — Experiment 05 Persistence Note

The "Don't show this introduction again" checkbox uses sessionStorage as a placeholder.

This preference should eventually be handled through user preferences or settings rather than local component state.

TODO: When user accounts are introduced, persist this preference to the user profile so it travels across devices and sessions.

## Future Note — Dark Mode

Dark mode is intentionally deferred.

Once the information architecture and visual hierarchy stabilise we will investigate whether an "Investigation Mode" (rather than a conventional dark mode) improves concentration.

This should be treated as a future UX experiment rather than an accessibility feature.