docs(confidence-engine): define progressive investigation workspace model
This commit is contained in:
+328
-12
@@ -378,7 +378,9 @@ 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.
|
||||
- **User validation gap:** Users need lightweight exception disposition controls — only "Not quite" and "Not relevant" are needed as explicit actions. All others default to accepted-by-default (still revisable). These have no semantic home under a contribution-only model.
|
||||
|
||||
> **Note (2026-08-26):** Earlier exploration treated "Agree / Not quite / Not relevant" as three equally explicit user actions. The current product direction supersedes this: the UI presents findings under "What this tells us," which establishes accepted-by-default interpretation. Only two exception actions are needed — see Findings Interaction + Attention Model below.
|
||||
- **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
|
||||
@@ -395,10 +397,11 @@ These cannot be combined into a single score without losing critical investigati
|
||||
|
||||
### 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
|
||||
- **Accepted by default** (no explicit action required) → user treats as working premise for the current investigation (not absolute proof; still revisable if later evidence or the user challenges it)
|
||||
- **Not quite** → interpretation needs correction (partially supported); user may reword/correct the finding; original engine wording retained in provenance
|
||||
- **Not relevant** → may be true but should not drive this investigation (discounted from active reasoning weight, preserved in provenance); not permanently excluded — may be reopened by later evidence
|
||||
|
||||
> Default state terminology: prefer `accepted-by-default` / `corrected-by-user` / `not-relevant`. Existing runtime values (`null`, `agree`, `not_quite`, `not_relevant`) may remain temporarily for compatibility, but the product contract does NOT require an explicit agreement interaction. Final runtime enum/state representation is unresolved implementation detail.
|
||||
|
||||
These dispositions carry semantic weight that the reasoning system should consume for confidence and handoff decisions.
|
||||
|
||||
@@ -495,7 +498,7 @@ The distinction is clearly useful enough that focused→global integration shoul
|
||||
|
||||
5. **Trust model:** focused reasoning proposes Findings/evidence → user disposition affects standing → case/update independently evaluates → authoritative graph changes happen only through case/update.
|
||||
|
||||
6. **User dispositions** (Agree / Not quite / Not relevant) are semantic signals that INFORM global reasoning. They do not directly bind graph truth.
|
||||
6. **User dispositions** — The current product direction uses `accepted-by-default` as the normal state and only two explicit exception actions (`Not quite`, `Not relevant`). Earlier versions documented these as three equally explicit actions (Agree / Not quite / Not relevant); that exploration phase is superseded by the accepted-by-default model. Dispositions are semantic signals that INFORM global reasoning. They do not directly bind graph truth.
|
||||
|
||||
7. **Finding status and graph node status remain separate concepts.** One does not dictate the other.
|
||||
|
||||
@@ -533,7 +536,7 @@ This section codifies the settled semantic boundaries for moving a Finding from
|
||||
|
||||
### Minimum handoff unit: FINDING-WITH-DISPOSITION-AND-PROVENANCE
|
||||
|
||||
The minimum viable object that crosses from focused to global is a **Finding** carrying its current proposition, status, at least one provenance contribution reference, and optionally an explicit user disposition. A Finding with no explicit disposition remains provisional and globally eligible for evaluation; it must not be treated as agreed, confirmed, or user-validated. Raw contributions alone are insufficient (no accumulated support). Full history is over-specified for v1.
|
||||
The minimum viable object that crosses from focused to global is a **Finding** carrying its current proposition, status, at least one provenance contribution reference, and optionally an exception disposition (`Not quite` or `Not relevant`). A Finding with no explicit disposition is accepted by default (not treated as agreed/confirmed/user-validated in the strong sense — it remains provisional to challenge but is accepted as working interpretation for the current investigation). Raw contributions alone are insufficient (no accumulated support). Full history is over-specified for v1.
|
||||
|
||||
### Required content classification
|
||||
|
||||
@@ -544,7 +547,7 @@ The minimum viable object that crosses from focused to global is a **Finding** c
|
||||
| Finding status | **REQUIRED** — drives global eligibility |
|
||||
| Finding relevance | **OPTIONAL** — advisory; case/update may override |
|
||||
| Finding standing/confidence | **OPTIONAL** — advisory |
|
||||
| current user disposition | **OPTIONAL** — explicit semantic signal; silence remains provisional, never agreement |
|
||||
| current user disposition | **OPTIONAL** — only needed for exception actions (`Not quite`, `Not relevant`); absence means accepted-by-default (still revisable) |
|
||||
| originating targetNodeId | **ORIGIN-ANCHOR-REQUIRED-WHEN-AVAILABLE** — expected when the Finding came from an existing focused investigation; does not predetermine final graph mapping |
|
||||
| source focused question | **PROVENANCE-ONLY** |
|
||||
| source user answer | **PROVENANCE-ONLY** |
|
||||
@@ -594,7 +597,7 @@ Raw contribution fields are not routine authoritative handoff state. They MAY be
|
||||
| Agree with contradictory evidence | ACCEPT-WITH-RESTRICTIONS — disposition accepted; weighed independently against contradicting evidence |
|
||||
| Not quite with no correction | ACCEPT-WITH-RESTRICTIONS — partial support recorded; needs refinement before strong standing |
|
||||
| Not relevant but high confidence | ACCEPT — relevance and confidence are separate dimensions |
|
||||
| No disposition / silence | ACCEPT — provisional Finding; eligible for case/update evaluation; never interpret lack of response as agreement |
|
||||
| No disposition / silence | ACCEPT — accepted-by-default; eligible for case/update evaluation as working interpretation (still revisable; not treated as absolute confirmation) |
|
||||
| Conflicting disposition history | ACCEPT-WITH-RESTRICTIONS — use latest; preserve conflict in provenance |
|
||||
| Disposition on materially changed proposition | REQUIRE-REFINEMENT — user may be responding to old wording |
|
||||
|
||||
@@ -620,7 +623,7 @@ Raw contribution fields are not routine authoritative handoff state. They MAY be
|
||||
| Empty proposition | REJECT |
|
||||
| Duplicate of existing Finding | ACCEPT-WITH-RESTRICTIONS (merge candidate; contradiction ≠ invalidity) |
|
||||
| Contradicts an agreed Finding | ACCEPT-WITH-RESTRICTIONS (evaluate through reconciliation) |
|
||||
| No user disposition / silence | ACCEPT — provisional state; never interpret silence as agreement |
|
||||
| No user disposition / silence | ACCEPT — accepted-by-default (working interpretation, still revisable); not absolute confirmation |
|
||||
| Marked not relevant | PROVENANCE-ONLY (retained but should not drive current priority) |
|
||||
| Target node already resolved | ACCEPT-WITH-RESTRICTIONS (may inform why resolution should be questioned) |
|
||||
| Originating target node no longer exists or unavailable | ACCEPT-WITH-PROVENANCE (origin missing does not invalidate Finding; case/update evaluates whether it exposes a new graph proposition) |
|
||||
@@ -688,7 +691,7 @@ A "not relevant" Finding crosses to case/update as provenance-only (discounted f
|
||||
|
||||
1. **Object crossing:** A current Finding plus standing/relevance/disposition state and provenance.
|
||||
2. **Provenance:** At least one traceable source contribution; originating investigation anchor retained when available. Missing origin does not invalidate the Finding.
|
||||
3. **Disposition:** Optional explicit user signal. Silence remains provisional, never agreement. Explicit dispositions: Agree (user-supported), Not quite (challenging/corrective), Not relevant (relevance disposition).
|
||||
3. **Disposition:** Only needed for exception actions. Default is accepted-by-default (working interpretation, still revisable — not absolute confirmation). Exception dispositions: `Not quite` (challenging/corrective) and `Not relevant` (relevance discount, retained in provenance). All other findings are accepted by default under "What this tells us."
|
||||
4. **Standing/relevance:** Semantic advisory state only; no weighting/scoring model assumed. case/update may independently set or override.
|
||||
5. **Mapping:** Originating target does not dictate final graph mapping; case/update determines graph impact/mapping including new propositions, multiple nodes, or unresolved mapping.
|
||||
6. **Authority:** Case/update solely owns graph mutation, Current Understanding and frontier selection. Finding identity (merge/split/identity) remains unresolved at the Finding layer.
|
||||
@@ -733,7 +736,7 @@ Each extracted observation in a focused deconstruction produces one provisional
|
||||
|
||||
#### 4. Handoff trigger
|
||||
**On completed contribution, provisional unless explicitly disposed.**
|
||||
A Finding is created immediately when a focused deconstruction completes and contributes its result. It enters case/update alongside the normal update payload. Explicit disposition (Agree / Not relevant) is optional — silence means `provisional` which is still globally eligible for evaluation.
|
||||
A Finding is created immediately when a focused deconstruction completes and contributes its result. It enters case/update alongside the normal update payload. Exception disposition (`Not quite` or `Not relevant`) is optional — absence means accepted-by-default (working interpretation, still revisable) which is globally eligible for evaluation.
|
||||
|
||||
#### 5. Best case/update seam
|
||||
**ScenarioForm → /api/cases/update → orchestrator → applyValidatedProposal.**
|
||||
@@ -886,3 +889,316 @@ The seam is NOT ready for implementation as described. The current architecture
|
||||
2. The graph-update prompt must remain free of finding context until isolation is verified at the architectural level — not just via output comparison.
|
||||
|
||||
Without this separation, any attempt to add findings to the existing update path risks coupling the full graph reasoning pipeline to finding evidence that has not yet been validated through the authoritative case/update evaluation gate.
|
||||
|
||||
---
|
||||
|
||||
## Findings Interaction + Attention Model — August 2026
|
||||
|
||||
### What this tells us = accepted by default
|
||||
|
||||
When findings are presented under "What this tells us," the normal default interpretation is:
|
||||
|
||||
> the Engine currently accepts each finding as its working interpretation for the current investigation
|
||||
|
||||
The user does NOT need to explicitly click "Agree" for every finding. Silence or absence of an exception action is interpreted as acceptance-by-default — not as absolute truth, but as a working premise that remains revisable if later evidence or the user challenges it.
|
||||
|
||||
### No explicit Agree interaction required
|
||||
|
||||
The earlier exploration model treated `Agree / Not quite / Not relevant` as three equally explicit user actions. That phase is superseded by the accepted-by-default direction:
|
||||
|
||||
- Only two exception actions are needed per finding
|
||||
- Explicit agreement is not a prerequisite for progression
|
||||
- Existing runtime values (including `null`, `agree`) may remain temporarily for compatibility, but the product contract does not require an explicit `agree` interaction
|
||||
|
||||
### Not quite = user correction / rewording
|
||||
|
||||
`Not quite` means:
|
||||
|
||||
> the finding is not an accurate enough representation of what the user meant
|
||||
|
||||
Expected interaction:
|
||||
|
||||
1. User selects "Not quite" on the specific finding
|
||||
2. UI exposes/edits the current finding wording for correction
|
||||
3. User corrects or rewords it
|
||||
4. The corrected wording becomes the current finding
|
||||
5. The original engine wording remains in provenance/history
|
||||
|
||||
Exact component design is not yet decided — this describes the semantic contract only.
|
||||
|
||||
### Not relevant = retained but discounted from current investigation
|
||||
|
||||
`Not relevant` means:
|
||||
|
||||
> the finding may be true, but should not drive the current investigation
|
||||
|
||||
Semantic effect:
|
||||
|
||||
- Retained in provenance
|
||||
- Discounted from current investigative relevance
|
||||
- Can be reopened later if new evidence makes it material
|
||||
|
||||
Do NOT delete a "not relevant" finding.
|
||||
|
||||
### Actions attach per finding
|
||||
|
||||
The exception actions attach to each individual finding bullet, not the whole section:
|
||||
|
||||
```
|
||||
What this tells us
|
||||
|
||||
• Team member handles supplier payments independently
|
||||
[Not quite] [Not relevant]
|
||||
|
||||
• Exceptions are escalated
|
||||
[Not quite] [Not relevant]
|
||||
|
||||
• Remaining routine work has not been fully mapped
|
||||
[Not quite] [Not relevant]
|
||||
```
|
||||
|
||||
This is conceptual only — not yet a component design.
|
||||
|
||||
### Default state terminology
|
||||
|
||||
Preferred conceptual states:
|
||||
|
||||
- `accepted-by-default` (no action taken — still revisable)
|
||||
- `corrected-by-user` (via Not quite path)
|
||||
- `not-relevant` (discounted from current relevance)
|
||||
|
||||
Existing implementation values (`null`, `agree`, `not_quite`, `not_relevant`) may remain temporarily for compatibility. Final runtime enum/state representation is an unresolved implementation detail.
|
||||
|
||||
### Silence / default ≠ absolute truth
|
||||
|
||||
Silence or absence of action does NOT mean the finding is permanently settled:
|
||||
|
||||
- It remains a working interpretation for the current investigation
|
||||
- It can be challenged or reopened if later evidence contradicts it
|
||||
- It differs from explicit confirmation in strength, not from being revisable
|
||||
|
||||
### Attention model — prominence follows current activity
|
||||
|
||||
The interface should primarily show what the user is working on now. Previous reasoning remains persistent and recoverable, but should recede unless relevant to the current task.
|
||||
|
||||
**While answering a question:**
|
||||
|
||||
- Prominent: current question, response field
|
||||
- Previous learning: collapsed / secondary
|
||||
|
||||
**Immediately after deconstruction:**
|
||||
|
||||
- Prominent: "What this tells us" findings with Not quite / Not relevant actions, Still unclear, next useful question
|
||||
- Previous turn detail: available but secondary
|
||||
|
||||
**When the next question is selected:**
|
||||
|
||||
- Prominent: new current question, response field
|
||||
- Prior findings recede again
|
||||
|
||||
**When "Not quite" is selected:**
|
||||
|
||||
- Prominent: that one finding with editable corrected wording
|
||||
- Other material recedes
|
||||
|
||||
All reasoning should NOT be shown simultaneously. The current UI accumulates too many overlapping sections (Current Understanding, Situation, Open Questions, active focused question, response, What this tells us, Still unclear, Questions this raises, Previous learning, assumptions, relationships, future Findings/dispositions). Showing all at once overloads the user.
|
||||
|
||||
### Synthesis model — natural workshop checkpoints
|
||||
|
||||
Cumulative Finding synthesis should NOT happen:
|
||||
|
||||
- After every answer
|
||||
- After a fixed number of findings
|
||||
- Automatically whenever a threshold is crossed
|
||||
|
||||
**Preferred product model:** investigate → accumulate findings → reach natural workshop checkpoint → offer synthesis → user explicitly chooses whether to run it.
|
||||
|
||||
Natural workshop checkpoints include:
|
||||
|
||||
- Current branch has run out of materially useful questions
|
||||
- Next questions are becoming narrow / repetitive
|
||||
- The user says they have enough information
|
||||
- The user explicitly chooses to step back and review
|
||||
|
||||
Useful facilitator wording:
|
||||
|
||||
> "We've covered the main useful questions in this part of the investigation. It may be worth stepping back now and seeing what the evidence adds up to."
|
||||
|
||||
**For v1: synthesis is user-triggered (explicit / user-led).** Automatic detection of workshop checkpoints is a later optimisation. No fixed finding-count threshold is defined at this time.
|
||||
|
||||
### Synthesis sequence (future intent)
|
||||
|
||||
```
|
||||
answer
|
||||
→ What this tells us findings
|
||||
→ user only intervenes on exceptions: Not quite, Not relevant
|
||||
|
||||
→ findings accumulate
|
||||
|
||||
→ natural workshop checkpoint reached
|
||||
|
||||
→ user chooses to analyse what has been learned
|
||||
|
||||
→ cumulative synthesis uses: current findings, user corrections, relevance decisions, provenance, relevant graph context
|
||||
|
||||
→ refreshed Current Understanding
|
||||
```
|
||||
|
||||
This synthesis is separate from routine focused deconstruction. The synthesis API is not designed in this contract.
|
||||
|
||||
### Findings remain reopenable
|
||||
|
||||
- `Not relevant today` does NOT mean `irrelevant forever` — later evidence may make an old finding material again
|
||||
- `Accepted-by-default` does NOT mean `permanently settled` — a finding may later be challenged or reopened
|
||||
- Both states are revisable with explicit status indicating why they were reopened
|
||||
|
||||
---
|
||||
|
||||
## Progressive Investigation UI + Notebook Workspace Model — August 2026
|
||||
|
||||
### Core principle: investigation depth shapes the interface
|
||||
|
||||
> The interface should progressively reveal the structure of the investigation as that structure emerges, while keeping the user's current reasoning task visually dominant.
|
||||
|
||||
The UI should NOT be a fixed shell that shows every available reasoning artefact at once. As the investigation evolves:
|
||||
|
||||
```text
|
||||
simple case → simple overview
|
||||
focused branch → focused investigation workspace
|
||||
findings accumulate → validation/correction becomes available
|
||||
branch matures → synthesis/review becomes appropriate
|
||||
later evidence reopens old → previously secondary material becomes prominent again
|
||||
```
|
||||
|
||||
The relationship is reciprocal: reasoning state shapes the UI, and UI structure guides the user toward the appropriate reasoning activity.
|
||||
|
||||
### Case overview = orientation / index surface
|
||||
|
||||
The main screen acts as a notebook index or case summary view.
|
||||
|
||||
Prominent elements:
|
||||
- Current Understanding
|
||||
- Situation
|
||||
- Open Questions
|
||||
|
||||
This screen is for orientation, choosing where to investigate, and seeing the main unresolved areas. It should NOT expand into an ever-growing full reasoning transcript.
|
||||
|
||||
Open Questions remain the top-level navigation entry point into deeper investigation.
|
||||
|
||||
### Focused investigation opens as a workspace overlay
|
||||
|
||||
Selecting a top-level Open Question opens a focused investigation workspace as a large overlay. The underlying case overview remains visible but dimmed/greyed; background content becomes inactive.
|
||||
|
||||
The overlay should feel like opening a page in a notebook rather than navigating to a completely separate application page. It should occupy enough of the viewport to function as a genuine reasoning workspace, not a small modal dialog.
|
||||
|
||||
**This supersedes earlier directions that treated inline accordion expansion as the primary long-term pattern.** The current product direction is overlay-first for focused investigation.
|
||||
|
||||
### Notebook interaction model (conceptual, not decorative)
|
||||
|
||||
```text
|
||||
CASE OVERVIEW = notebook index / case summary
|
||||
OPEN QUESTION = investigation page/topic
|
||||
FOCUSED OVERLAY = opened investigation page
|
||||
FINDINGS = notes learned on that page
|
||||
PREVIOUS LEARNING = earlier notes/history available beneath current work
|
||||
SYNTHESIS = step back and review what the notebook now adds up to
|
||||
```
|
||||
|
||||
Do NOT prescribe decorative notebook styling, paper textures, or tabs. The analogy is about information hierarchy and navigation.
|
||||
|
||||
### Overlay close behaviour
|
||||
|
||||
The workspace overlay has a prominent, persistent close control in the top-right (e.g., `× Close investigation`).
|
||||
|
||||
**Closing means:**
|
||||
- Leave this focused workspace
|
||||
- Return to the Open Questions overview
|
||||
- Preserve all investigation state
|
||||
|
||||
**Closing does NOT mean:**
|
||||
- Finish the branch
|
||||
- Discard work
|
||||
- Mark resolved
|
||||
- Run synthesis
|
||||
- Restart investigation
|
||||
|
||||
### Attention hierarchy inside the workspace
|
||||
|
||||
Content prominence follows current activity.
|
||||
|
||||
**While answering a question:**
|
||||
- Primary: current question, response field, submit action
|
||||
- Secondary (collapsed): previous learning, older findings, assumptions, relationships, other branch history
|
||||
|
||||
**Immediately after deconstruction:**
|
||||
- Primary: "What this tells us", Still unclear, next useful question
|
||||
- Each finding under "What this tells us" exposes exception actions: Not quite, Not relevant
|
||||
|
||||
**When "Not quite" is selected:**
|
||||
- Primary: the affected finding with editable/rewordable correction
|
||||
- Other workspace content recedes visually; original Engine wording remains in provenance
|
||||
|
||||
**When next question is selected:**
|
||||
- Primary focus returns to new current question and response
|
||||
- Prior findings remain persistent but recede
|
||||
|
||||
### Finding interaction model
|
||||
|
||||
"What this tells us" presents findings accepted by default as the Engine's current working interpretation. Accepted by default does NOT mean absolute truth — it means a working premise for the current investigation, still revisable if later evidence or the user challenges it.
|
||||
|
||||
The user intervenes only by exception:
|
||||
- **Not quite** → correct/reword the finding; original wording retained in provenance
|
||||
- **Not relevant** → retain the finding but discount it from the current investigation
|
||||
|
||||
Actions apply per finding, not to the entire section. No explicit Agree action is required.
|
||||
|
||||
### Progressive disclosure
|
||||
|
||||
The UI will increasingly hold: questions, answers, findings, corrections, relevance decisions, previous learning, uncertainties, assumptions, relationships, provenance, and future synthesis. Therefore:
|
||||
|
||||
> Persistent does not mean permanently visible.
|
||||
|
||||
Older material should remain recoverable without competing with the current task. Not all reasoning artefacts need to remain expanded simultaneously.
|
||||
|
||||
### Natural synthesis checkpoint
|
||||
|
||||
Cumulative synthesis is separate from routine investigation. Do NOT trigger synthesis after every turn, after a fixed number of findings, or automatically just because data volume grows.
|
||||
|
||||
Preferred flow:
|
||||
```text
|
||||
investigate branch → accumulate findings → reach natural workshop checkpoint → offer review → user explicitly chooses synthesis
|
||||
```
|
||||
|
||||
Natural checkpoints include:
|
||||
- Useful questions are running out
|
||||
- Remaining questions are becoming narrow/repetitive
|
||||
- The user says they have enough information
|
||||
- The user chooses to step back and review
|
||||
|
||||
Facilitator-style concept (wording not final):
|
||||
> "We've covered the main useful questions in this part of the investigation. It may be worth stepping back now and seeing what the evidence adds up to."
|
||||
|
||||
For v1: synthesis is user-triggered (explicit / user-led). Automatic detection of workshop checkpoints is a later optimisation.
|
||||
|
||||
### UI attention modes (conceptual)
|
||||
|
||||
```text
|
||||
1. ORIENT — case overview, orientation
|
||||
2. INVESTIGATE — focused workspace overlay
|
||||
3. VALIDATE — review/correct findings from the current answer
|
||||
4. SYNTHESISE — explicit cumulative review at a natural checkpoint
|
||||
```
|
||||
|
||||
These are conceptual attention modes, not implemented routing/state machines. Separate pages are not assumed to be required.
|
||||
|
||||
### Explicitly unresolved
|
||||
|
||||
- Overlay dimensions / layout
|
||||
- Animation
|
||||
- Mobile behaviour
|
||||
- Exact close-control styling
|
||||
- Exact finding-control styling
|
||||
- Previous-learning collapse design
|
||||
- Synthesis visual design
|
||||
- Automatic checkpoint detection
|
||||
- Final facilitator wording
|
||||
|
||||
Reference in New Issue
Block a user