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
@@ -434,3 +434,45 @@ For end users, present the same data as:
 - **Quiet reasoning summary** — raw counts (nodes, edges, etc.) visually secondary

 Internal graph concepts should remain available for developers (Developer Details) but should not dominate the primary view. The panel should feel like a facilitator's notebook: someone looking at it should immediately understand where the investigation stands, what has been learned, and what remains uncertain — without needing to understand graph theory.
+
+## Graph Projection
+
+The reasoning engine produces a rich graph with structured concepts (observations, unknowns, assumptions, relationships, metrics, states). The UI increasingly becomes a translation layer over this graph rather than maintaining separate duplicated summaries.
+
+This section records principles for projecting graph data into human-meaningful views.
+
+### Translation over exposure
+
+- The graph is internal structure; the UI communicates human meaning.
+- User-facing panels should translate graph state rather than expose graph terminology.
+- Display only the amount of graph information useful for the current task.
+
+### Epistemic clarity
+
+- Known information, uncertainty and assumptions must remain visibly distinct.
+- Assumptions must never look like facts.
+- Use explicit structural labels (e.g., "Possible explanation", "Not yet established") rather than relying on colour or implicit cues.
+
+### Curation as explanation
+
+- Prioritisation and omission are part of good explanation.
+- Repeated scenario text should not dominate derived summaries.
+- Complete technical detail remains available through Developer Details.
+
+### Robustness constraints
+
+- Meaning must remain understandable without relying on colour.
+- Displayed content must be grounded in existing graph fields — never invent facts absent from the graph.
+- When nothing useful is established, show calm fallback language rather than an empty panel or a fabricated summary.
+
+### Label hygiene
+
+- Prefer labels over descriptions when labels are clearer.
+- Normalise text for deduplication (lowercase, trim, collapse whitespace).
+- Omit items that are too verbose to scan; do not synthesise rewritten claims that change meaning.
+- Avoid displaying graph identifiers, confidence values without context, or raw enum categories in user-facing views.
+
+### State-aware framing
+
+- The same panel must remain useful during early, active and terminal investigation states.
+- Terminal state content should change its framing (e.g., "What the evidence supports" rather than "Still investigating") but not invent certainty.