robbond/confidence-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(confidence-engine): consolidate current context and provenance

Browse Source
This commit is contained in:
robbond
2026-09-03 09:37:04 +01:00
parent 7db28c8611
commit 577781eff8
4 changed files with 253 additions and 542 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/current-project-state.md
+48 -10
View File
@@ -20,14 +20,21 @@ The user may already know the answer but needs confidence to act, may need to id
## 2. Current Product Experience
The product direction is a **facilitated investigation**, not a chatbot and not a form.
The product direction is a **facilitated investigation** presented across three distinct routes:
- A conversation lane guides the user through one question at a time;
- A shared workspace (situation, understanding, investigation map, history) presents the current state alongside the active question;
- A graph is used as the machine representation of reasoning, translated into human-readable narrative for the user view;
- Developer and debug views remain available but are intentionally separate.
```
/ → Portfolio (investigator notebook index)
/investigations/case-1 → Investigation (working case / pages)
/investigations/case-1/report → Investigation Report (readable derived summary)
```
UI work is currently paused. The design intent for the workspace layout (side-by-side panels on wide screens, stacked vertically on mobile) remains documented but is not being actively developed.
**Portfolio:** Shows the single canonical persisted investigation card. Actions: *View report*, *Continue investigation*, *Restart investigation*. Below the card: *+ Create new investigation*. Restart is confirmation-gated and destructive.
**Investigation:** Contains `ScenarioForm` + `ReasoningWorkspace`. Handles graph reasoning, focused investigation turns, Done/Re-open semantics, Current Understanding synthesis. Report presentation is NOT part of this route — owned by the dedicated Report page.
**Report:** Renders persisted `investigationReport` snapshot. Generation is on-demand (exactly one `/api/cases/overview` call on first visit; zero on subsequent visits). The Report is a derived artefact, not canonical reasoning evidence.
The user controls which question to investigate, when to say Done for now, whether Current Understanding is sufficient, whether to reopen work, and when to review the Report. The engine facilitates — it does not steer or prioritise.
## 3. Current Engine Capabilities
@@ -48,13 +55,30 @@ These are what currently affect the working engine:
> is also paused. Question formulation remains available as a capability but its
> output is not automatically enforced as the user's required next step.
### Route architecture (v0.55)
Three distinct routes, each with clear ownership:
| Route | Owner | Presentation |
|---|---|---|
| `Portfolio` (`/`) | Portfolio page + storage | Card with actions; no Report presentation |
| `Investigation` (`/investigations/case-1`) | `ScenarioForm` + `ReasoningWorkspace` | Focused investigation turn cycle |
| `Report` (`/investigations/case-1/report`) | Report page (standalone) | Persisted derived artefact; on-demand generation |
**Key invariants:** ReasoningWorkspace no longer owns Report presentation. The Report is a distinct route/page, not an internal state of the Investigation.
### Persistence and report lifecycle
- Single canonical persisted investigation via localStorage (`confidence-engine-investigation` key).
- `saveInvestigation()` / `loadInvestigation()` are the canonical storage seams.
- Report generation: first visit → one synthesis call + persist; subsequent visits → zero calls, renders persisted snapshot.
- Restart is destructive and confirmation-gated (dialog → explicit second confirmation → `clearInvestigation()`).
### Reasoning-engine vs UX/product version lineage
The Confidence Engine tracks two independent version lineages:
- **Reasoning-engine experimental lineage** (v0.8+): reasoning-fidelity, investigation-state assessment, semantic selectors — under RTO pause.
- **UX/product development lineage** (v0.7): workspace layout, user views, loading feedback — also paused.
Do not conflate these lineages as describing one product version.
- **UX/product development lineage** (v0.55+): Portfolio / Investigation / Report route separation, persisted report lifecycle, confirmation-gated restart, focused-presentation ownership, empty Done semantics. Do not conflate these lineages as describing one product version.
### Passive experimental capabilities
@@ -82,6 +106,16 @@ The following were built during Experiments 18–25B. They are isolated diagnost
## 5. What Remains Unresolved
### Not yet implemented (product capabilities)
- Multi-investigation portfolio (search/tag/archive/group behaviour)
- Durable investigation identities beyond `case-1`
- Report freshness / versioning after investigation changes
- Export/copy of Reports to Jira or external document
- Portfolio expansion beyond one canonical investigation
### Methodological unresolved
- How free language will be interpreted reliably without keyword scaffolding;
- Whether structured LLM interpretation should eventually replace current phrase-based detection;
- Whether passive classifiers generalise across domains or remain fixture-specific;
@@ -115,7 +149,11 @@ Historical documents are retained under `docs/archive/` and should be opened onl
## 8. Return-to-Work Summary
Engine experiments advanced through Experiment 43, which diagnosed Clarify's absence across all real fixtures (zero eligibility in 10 turns). The orienting-based Clarify rule is dead code — the assessor never produces phase=orienting. The too_broad trigger is validly narrow but untested by any fixture. Summarise and Pause remain operational from Exp 42. Behaviour Selection remains passive and isolated. Open decision: whether to fix the orienting dead-code path or accept it as intentional design, and whether to widen or tighten the too_broad threshold with dedicated fixtures. No active tests rerun as part of documentation closure.
Engine experiments advanced through Experiment 43, which diagnosed Clarify's absence across all real fixtures (zero eligibility in 10 turns). The orienting-based Clarify rule is dead code — the assessor never produces phase=orienting. The too_broad trigger is validly narrow but untested by any fixture. Summarise and Pause remain operational from Exp 42. Behaviour Selection remains passive and isolated.
UX/product development reached v0.55: Portfolio / Investigation / Report route separation, persisted report lifecycle (first visit = one synthesis; subsequent visits = zero), confirmation-gated restart, focused-presentation ownership per question, empty Done + Re-open semantics, zero-Open-Questions milestone. All verified via targeted Vitest and live Playwright.
First document to read: **`docs/current-handoff.md`** (methodology continuity + current state), then `docs/current-project-state.md`, then `docs/project-knowledge-inventory.md`. Consult `.claude/architecture-guardrails.md` before any code changes. The full experiment history remains available in `docs/design-evolution-log.md` but is no longer default reading — load only when a specific question requires it.
First document to read: **`docs/current-handoff.md`** (methodology continuity + current state), then `docs/current-project-state.md`, then `docs/project-knowledge-inventory.md`. Consult `.claude/architecture-guardrails.md` before any code changes. The full experiment history remains available in `docs/design-evolution-log.md` but is no longer default reading — load only when a specific question requires it.