7.4 KiB
Investigation Narrative — Architecture Design
This is a design document only. Do not implement yet.
Purpose
The reasoning graph contains everything the engine knows, why it knows it, and how it connects to other knowledge. It is an excellent internal reasoning model but a poor presentation model for end users.
This document proposes an intermediate architectural layer — the Investigation Narrative — that sits between the reasoning graph and the UI.
The narrative translates machine structure into human understanding without altering the reasoning engine, the graph schema, or any external contract.
Architecture
User
↓↑
Facilitator UI (workspace projection)
↓↑
Investigation Narrative (presentation model)
↓↑
Reasoning Graph (reasoning model)
↓↑
LLM / Ollama / Reasoning Engine
↓↑
User
Why this layer is needed
- The graph's nodes and edges describe how the engine knows. Users need to understand what is known and what remains uncertain.
- Multiple UI projections (facilitator view, developer details, investigation map) can share a single narrative without each re-implementing its own translation of the graph.
- The narrative can evolve independently of both the graph schema and the UI layout.
Proposed Narrative Structure
Each section describes:
- Purpose — why it exists in the narrative
- Source — where it comes from in the graph
- Deterministic — whether it is derived algorithmically or requires judgment
- Audience — who consumes it
Current Question
- Purpose: Tell the user what to think about next.
- Source: The highest-priority unresolved unknown or assumption node in the graph.
- Deterministic: Yes, if priority rules are fixed.
- Audience: The user (primary).
Current Understanding
- Purpose: Summarise what is known so far.
- Source: Resolved nodes and confirmed observations from the graph, filtered for relevance.
- Deterministic: Yes.
- Audience: The user.
Known Facts
- Purpose: List established findings.
- Source: Graph nodes with status "resolved" that are not scaffolding or procedural.
- Deterministic: Yes.
- Audience: The user; also consumed by other narrative sections.
Active Unknowns
- Purpose: Show what is still being investigated and why it matters.
- Source: Graph nodes with status "unknown" or "assumption" that have not been resolved.
- Deterministic: Yes, with pruning for relevance.
- Audience: The user.
Current Line of Enquiry
- Purpose: Explain what the investigation is focusing on right now.
- Source: Connected subgraph around the active unknown — parent nodes and adjacent reasoning paths.
- Deterministic: Yes, if path selection rules are fixed.
- Audience: The user (context).
Possible Explanations
- Purpose: Present alternative hypotheses without asserting any as true.
- Source: Assumption nodes and explanation-type nodes that have not been confirmed.
- Deterministic: Yes, with epistemic labels.
- Audience: The user (evaluating evidence).
Evidence Gathered
- Purpose: Show what the user has contributed and what the engine has discovered.
- Source: Observation nodes in the graph.
- Deterministic: Yes, deduplicated by normalised text.
- Audience: The user (confidence and traceability).
Confidence Signals
- Purpose: Communicate how certain the engine is — without implying false precision.
- Source: Resolution ratio, number of unresolved nodes, depth of supporting paths.
- Deterministic: Yes, as ratios or qualitative descriptors ("partial", "substantial", "limited").
- Audience: The user (calibrating trust).
Reason Investigation Continues
- Purpose: Explain why the engine has not reached a terminal state.
- Source: Active unknowns and their supporting gaps in the graph.
- Deterministic: Yes, derived from unresolved subgraphs.
- Audience: The user (closure and motivation).
Recent Progress
- Purpose: Show what changed since the last turn.
- Source: Nodes whose status changed or whose evidence count changed between states.
- Deterministic: Yes.
- Audience: The user (continuity and momentum).
Suggested Next Step
- Purpose: Give the user a concrete, minimal action.
- Source: The current unknown + what information would resolve it (derived from its parent edges).
- Deterministic: Yes, if suggestion rules are fixed.
- Audience: The user (next interaction).
Completion Summary
- Purpose: Present the final findings when the investigation reaches a terminal state.
- Source: All resolved nodes, reorganised into coherent findings rather than node lists.
- Deterministic: Yes, with curation for coherence.
- Audience: The user (closure and reference).
Narrative Composition Rules
Never invent facts
Every narrative element must be traceable to one or more graph nodes. No content may appear in the narrative that does not exist somewhere in the reasoning graph.
Preserve epistemic certainty
If the graph expresses uncertainty, the narrative must express it — not by showing confidence percentages but by using language like "possibly", "to be tested", "not yet established".
Explain, do not expose
The narrative should answer: what does this mean? rather than how was this computed? Graph mechanics (node IDs, edge types, traversal depth) belong in Developer Details, not in the user-facing narrative.
Shared source of truth
A single narrative object should be produced from the graph and consumed by all UI panels. Panels should not reimplement their own derivation logic.
State-aware framing
The same narrative fields are always available, but their labels and emphasis change based on investigation phase:
- Early: "What we know", "What we need to understand"
- Active: "Current understanding", "Still investigating", "Next question"
- Terminal: "Findings", "What the evidence supports", "Remaining uncertainty"
Layer Responsibilities
Reasoning Graph
Responsible for:
- reasoning
- evidence
- relationships
- uncertainty
- provenance
- machine state
Not responsible for:
- storytelling
- explanation
- user wording
Investigation Narrative
Responsible for:
- translating graph meaning
- selecting relevant information
- organising investigation state
- communicating progress
- preserving epistemic certainty
Not responsible for:
- reasoning
- inference
- evidence generation
UI (Facilitator Panels)
Responsible for:
- presentation
- interaction
- accessibility
- cognitive load
Not responsible for:
- deciding meaning
- interpreting graph nodes
Emergent Architecture
The Confidence Engine architecture is becoming:
- User — observes, thinks, responds
- Facilitated Conversation — the active question-response loop
- Reasoning Graph — machine representation of all knowledge and uncertainty
- Investigation Narrative — human representation of current understanding
- Workspace Projection — UI panels rendering the narrative
- User — reads, evaluates, contributes evidence
The reasoning graph is the machine representation.
The investigation narrative is the human representation.
The UI simply renders whichever projection is appropriate.
This is an emerging architectural direction. It is intentionally recorded before implementation so future experiments remain aligned.