docs(confidence-engine): establish contributions and findings distinction

2026-08-26 14:07:05 +01:00
parent cb707c0192
commit b26ea7d0ba
1 changed files with 128 additions and 0 deletions
@@ -346,3 +346,131 @@ STILL OPEN
 ### Important separation note
 The latest second-turn semantic output exposed a separate reasoning issue around assumption attribution/frontier prioritisation. This must not be conflated with the UI duplication defect described above. They are orthogonal concerns — one is presentation state management, the other is semantic reasoning fidelity.
 ---
 ## CONTRIBUTIONS → FINDINGS DOMAIN MODEL (2026-08-26)
 ### Discovery scope
 This section records a domain model discovery based on live manual walkthrough evidence across multiple focused deconstruction turns. It determines whether the Confidence Engine needs an explicit distinction between **Contribution**, **Finding**, and **Investigation** for use in the eventual focused→global handoff.
 ### Key finding: Contribution ≠ Finding
 ```text
 Contribution:
  immutable provenance from one answer interpretation.
  Captures: what the model observed about what the user said at one turn.
  Contains: observations, uncertainties, assumptions, relationships, follow-ups.
  Mutated: NO — it is a record of one interpretation event.
 Finding:
  living conceptual proposition/theme in the investigation.
  Accumulates support from multiple contributions across turns and branches.
  Carries user disposition (agreed / challenged / not relevant).
  Can change standing; can be reopened by new evidence.
 ```
 ### Why contributions alone are insufficient
 Evidence from live walkthrough:
 - **Same idea across turns:** Same conceptual themes emerge in different wording across multiple focused deconstruction turns. Without higher-level grouping, these appear as disconnected observations.
 - **Latest-result replacement:** `focusedInvestigations[nodeId].result` only holds the latest result. Older findings disappear even when still conceptually valid.
 - **Cross-branch evidence:** A previous finding may gain or lose significance when new evidence appears on a different branch. The turn-based model has no mechanism to express this cross-branch linkage.
 - **User validation gap:** Users need lightweight disposition controls (Agree / Not quite / Not relevant). These have no semantic home under a contribution-only model.
 - **Reopening needed:** A previously "not relevant" finding may become material again when later evidence connects to it. No durable entity exists to carry this state across turns.
 ### Truth vs relevance must be separate dimensions
 ```text
 true but irrelevant — supported by evidence, does not drive current investigation
 relevant but uncertain — important question with limited supporting evidence
 agreed and highly relevant — user confirmed; strong global reasoning input
 challenged but still important — imprecise but guides investigation direction
 previously irrelevant, reopened by new evidence — status changed, weight restored
 ```
 These cannot be combined into a single score without losing critical investigation state.
 ### User dispositions are semantic, not UI-only
 - **Agree** → user treats as working premise (not absolute proof)
 - **Not quite** → interpretation needs correction (partially supported)
 - **Not relevant** → may be true but should not drive this investigation (discounted from active reasoning weight, preserved in provenance)
 - **Silence remains provisional** — never interpret lack of response as agreement
 These dispositions carry semantic weight that the reasoning system should consume for confidence and handoff decisions.
 ### Reopening principle
 > A finding should be durable, but its standing and relevance should remain revisable when new evidence appears elsewhere.
 Reopening = new evidence has made a previously settled / discounted / irrelevant proposition material to the investigation again. The previous disposition is preserved in provenance; the finding gains new weight with explicit status indicating why it was reopened.
 ### Contribution → Finding relationship
 - **Cardinality:** Many-to-one (multiple contributions converge on one evolving conceptual finding)
 - **Provenance:** Essential — every finding must track which contributions support it, which dispositions were applied, and what later evidence supports or challenges it
 ### SituationGraph relationship
 A Finding is a **user-facing grouping** over one or more graph propositions. It is not simply another name for an existing graph node, nor is it unnecessary — it is the conceptual layer the user reasons about, built on top of graph nodes as structural anchors.
 ### Impact on focused → global handoff
 **Material change:** The handoff question shifts from "copy raw focused fields into global reasoning" to:
 ```text
 focused contribution
  → candidate / evolving finding
  → user disposition + provenance + later evidence
  → finding standing changes
  → eligible global reasoning input
 ```
 **Blindly converting observations/uncertainties/assumptions/relationships into graph mutations would be unsafe because:**
 - Assumptions may be wrong (model misattribution)
 - Relationships may overreach (co-mention ≠ causation)
 - Relevance may change across investigation branches
 - Tentative language may have been strengthened in a later turn
 - Findings may later be reopened — their status is not final at handoff time
 ### Global eligibility matrix
 | Item | Eligibility |
 |------|-------------|
 | Raw contribution | LOCAL/PROVENANCE-ONLY (unless no finding exists) |
 | Provisional finding | GLOBAL-ELIGIBLE-WITH-STATUS (reduced weight) |
 | Agreed finding | GLOBAL-ELIGIBLE (strong support) |
 | Challenged / not-quite | GLOBAL-ELIGIBLE-WITH-STATUS (partial support) |
 | Not-relevant finding | LOCAL/PROVENANCE-ONLY (discounted, preserved) |
 | Reopened finding | GLOBAL-ELIGIBLE-WITH-STATUS (weight restored by new evidence) |
 | Superseded finding | GLOBAL-ELIGIBLE-WITH-STATUS (use superseding finding) |
 | Unresolved finding | GLOBAL-ELIGIBLE-WITH-STATUS (triggers further investigation) |
 ### Primary user-facing reasoning object
 **Findings**, not contributions or turn history. Contributions and turns are provenance underneath; findings are what the user actually reasons about. The investigation is conceptually about building understanding, not collecting answer-interpreters.
 ### Product principle alignment
 > "The Engine's primary job is to progressively build a trustworthy representation of the situation. Questions are the mechanism used to improve that representation."
 **STRONGLY-ALIGNS.** Confirmed by both the Return-to-Origin methodology and live walkthrough evidence. The engine's product is the trustworthy representation (findings + confidence), not the graph structure or question sequence.
 ### Confidence emerges from:
 - Confirmed findings (agreed)
 - Provisional findings (accumulating support)
 - Challenged findings (partial, needs refinement)
 - Irrelevant/discounted findings (understood, not driving)
 - Contradictions between findings
 - Unresolved gaps
 - Evidence provenance (how many contributions support each finding)
 - Stability under new evidence
 - Ability to reopen findings when relevance changes
 ### Decision: FINDINGS-DOMAIN-MODEL-JUSTIFIED
 The distinction is clearly useful enough that focused→global integration should be designed around findings/provenance rather than raw turn outputs. The semantic gap between "what one answer contributed" and "what the investigation has found so far" is real and material.