experiment: facilitator view from reasoning graph

2026-08-05 15:00:42 +01:00
parent a7b7dda91f
commit 1998b84ae1
6 changed files with 794 additions and 12 deletions
@@ -502,6 +502,25 @@ The current "Investigation in progress" panel exposes developer-oriented statist

 ---

+## 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.
@@ -531,14 +550,59 @@ A facilitator-style panel should communicate:
 - 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

-Pending visual review.
+Pending visual and live-data review.

 #### Status

 Experimental.

+Do not record a conclusion yet.
+
 ---

 ## Emerging Direction
@@ -143,3 +143,38 @@ The current adapter (`lib/map/investigation-map-adapter.js`) uses generic placeh
 7. **Investigation duration tracking**: The summary panel computes elapsed time from `Date.now() - updatedAt`. If the engine emits proper timestamps, the UI can show accurate elapsed duration and investigate stalls (>5 min between turns).

 8. **Layout independence (v0.7 workspace layout phase)**: Reasoning outputs must remain entirely independent of presentation layout. The UI's responsive workspace layout — which progressively reveals simultaneous context on wide screens — is a pure presentation concern. No reasoning contract field should be added, removed, or modified to accommodate layout changes. Future reasoning outputs should carry data semantically; how that data arranges itself visually is the responsibility of the presentation layer alone.
+
+---
+
+## Facilitator View Projection (Experiment 12)
+
+Version C derives its content from existing graph fields without requiring new backend data. The following fields are used as inputs:
+
+| Input | Source |
+|-------|--------|
+| node type / kind | `node.kind` (observation, unknown, assumption, state, metric, conclusion) |
+| node label or description | `node.label`, `node.description` |
+| support / status | `node.status`, `resolvedNodeIds` |
+| confidence where available | `node.confidence` |
+| active unknown identity | `graph.activeUnknownNodeId` |
+| resolution state | `node.status === "resolved"` or `resolvedNodeIds.includes(id)` |
+| evidence references where available | `node.evidenceIds` (currently empty in mocks) |
+| relationship relevance where available | `edge.relevance`, `node.relationships` |
+
+### Current limitations (observations, not requests)
+
+The following are observed constraints of the current graph output. They are documented here because they affect the adapter's filtering and ranking logic. They should NOT be treated as backend change requests during this experiment.
+
+- Graph text may repeat the full original scenario verbatim in node labels or descriptions.
+- Labels may be verbose relative to what a user can scan quickly.
+- The selected question rationale and the selected question itself may diverge slightly in wording from the underlying unknown node.
+- Ranking signals (relevance, priority) may not be sufficient for ideal user-facing ordering; the adapter uses deterministic fallbacks.
+- Some assumptions may be too generic to be useful without context.
+- Duplicate semantic content may occur across node types (e.g., an observation and an unknown restating the same scenario fragment).
+
+The adapter handles these limitations through:
+
+1. Length-based filtering of overly verbose items;
+2. Normalised text deduplication across node kinds;
+3. Deprioritisation of items matching known boilerplate patterns;
+4. Deterministic ranking with explicit fallback ordering documented in code comments.