robbond
1273861f0c
Implement the three-dimensional assessment (phase, progress, conversation health) that sits between narrative and behaviour selection. Key changes: - lib/assessment/investigation-state-assessor.js: assessor module with countObservations, assessPhase, assessProgress, assessConversationHealth, assessInvestigationState — deterministic classifiers using known rules - tests/investigation-state-assessor.test.js: 51 tests covering phase classification (orienting→concluding), progress thresholds, health conditions, confidence aggregation, edge cases, and observation counting - lib/graph/orchestrator.js: integration calls passing correctly-shaped input to assessInvestigationState() at three call sites (~552, ~904, ~1013) Design decisions encoded in this iteration: - countObservations counts nodes with known/resolved status + high-confidence non-unknown non-state nodes (not just explicit observation-kind nodes) - Phase uses seven values including cannot_determine for insufficient data - Progress uses resolution ratio thresholds: accelerating (>0.6), steady (0.2-0.6), stalled (<0.2 with ≥1 resolved) - Overall confidence = minimum across all three dimensions (conservative) Also adds investigation-state-assessment-contract.md and updates design-evolution-log, investigation-state-assessment.md (status header), and investigation-turn-cycle.md (implementation status table).
288 lines
9.5 KiB
Markdown
288 lines
9.5 KiB
Markdown
# Investigation Turn Cycle — Architecture Experiment 17
|
|
|
|
> This is a design document only. Do not implement yet.
|
|
|
|
---
|
|
|
|
## Hypothesis
|
|
|
|
A complete investigation can be described as a repeating turn cycle in which every architectural layer has a single responsibility.
|
|
|
|
Each turn follows a deterministic sequence of stage transitions. No stage performs the work of another. Feedback flows upward through the same layers it passes on the way down.
|
|
|
|
---
|
|
|
|
## The Turn Cycle
|
|
|
|
```
|
|
User submits an observation
|
|
↓
|
|
Reasoning Graph updates
|
|
↓
|
|
Investigation Narrative updates
|
|
↓
|
|
State Assessment evaluates progress
|
|
↓
|
|
Behaviour Selection determines response type
|
|
↓
|
|
Conversation generates response
|
|
↓
|
|
Workspace projects state
|
|
↓
|
|
Wait for next user observation
|
|
```
|
|
|
|
Each stage below describes its purpose, inputs, outputs, and constraints.
|
|
|
|
---
|
|
|
|
## Stage 1 — User Observation
|
|
|
|
### Purpose
|
|
|
|
The investigation begins when the user provides a new observation, confirmation, correction, or additional context.
|
|
|
|
### Inputs
|
|
|
|
Nothing system-generated. This stage is entirely user-driven.
|
|
|
|
### Outputs
|
|
|
|
A text contribution that becomes the raw material for graph reasoning.
|
|
|
|
### Must Never
|
|
|
|
- Anticipate what the user will say.
|
|
- Pre-fill or suggest content before the observation arrives.
|
|
- Treat the observation as a completed analysis — it is a starting point.
|
|
|
|
---
|
|
|
|
## Stage 2 — Reasoning Graph Update
|
|
|
|
### Purpose
|
|
|
|
Update the internal machine representation of knowledge with the new observation. Determine what changed: what was confirmed, what was contradicted, what new unknowns emerged, and how existing nodes relate to the new information.
|
|
|
|
### Inputs
|
|
|
|
- Current reasoning graph (all known nodes, edges, states).
|
|
- User's observation text.
|
|
|
|
### Outputs
|
|
|
|
- Updated graph with new or modified nodes.
|
|
- Status markers: resolved, confirmed, contradicted, introduced, unchanged.
|
|
- Newly created edges representing relationships between old and new information.
|
|
- Provenance links tracing each conclusion back to user input.
|
|
|
|
### Must Never
|
|
|
|
- Produce narrative language.
|
|
- Select facilitator behaviour.
|
|
- Decide what the user should see.
|
|
- Skip updating when the observation contradicts existing knowledge.
|
|
- Invent connections the evidence does not support.
|
|
|
|
---
|
|
|
|
## Stage 3 — Investigation Narrative Update
|
|
|
|
### Purpose
|
|
|
|
Translate the updated graph into a coherent human-understandable representation of investigation state. This is what the investigator currently knows, what remains uncertain, and how understanding has changed since the last turn.
|
|
|
|
### Inputs
|
|
|
|
- Updated reasoning graph from Stage 2.
|
|
|
|
### Outputs
|
|
|
|
A structured narrative containing:
|
|
- Current understanding (what is known).
|
|
- Active unknowns (what remains to be investigated).
|
|
- Evidence gathered (contributions and discoveries).
|
|
- Confidence signals (qualitative certainty indicators).
|
|
- Reason investigation continues (why we are not complete).
|
|
- Recent progress (what changed since last turn).
|
|
|
|
### Must Never
|
|
|
|
- Generate new reasoning or evidence.
|
|
- Decide what behaviour to deploy.
|
|
- Omit information that exists in the graph.
|
|
- Invent facts not traceable to graph nodes.
|
|
- Present developer-oriented graph structure to the user.
|
|
|
|
---
|
|
|
|
## Stage 4 — State Assessment
|
|
|
|
### Purpose
|
|
|
|
Evaluate where the investigation is across multiple analytical dimensions so that behaviour selection can operate on *state* rather than *implementation details*. This layer answers: "Given where we are, what kind of help is most appropriate right now?"
|
|
|
|
### Inputs
|
|
|
|
- Investigation Narrative from Stage 3.
|
|
- Turn history (previous assessments and their trajectories).
|
|
|
|
### Outputs
|
|
|
|
A structured assessment across seven dimensions:
|
|
1. **Current Investigation Phase** — Orienting / Exploring / Focusing / Deepening / Synthesising / Concluding
|
|
2. **Investigation Progress** — Accelerating / Steady / Stalled / Looping / Spiralling
|
|
3. **Evidence Quality** — Weak / Mixed / Strong / Contradictory
|
|
4. **Understanding Trajectory** — Growing / Static / Confused / Consolidating
|
|
5. **Uncertainty Trend** — Increasing / Reducing / Stable / Asymmetric
|
|
6. **Conversation Health** — Healthy / Repetitive / Too broad / Too narrow / User overloaded / User under-informed
|
|
7. **Behaviour Readiness** — Which behaviours are available, pressed for, inappropriate, or stable
|
|
|
|
### Must Never
|
|
|
|
- Select a behaviour directly.
|
|
- Inspect graph nodes or edges.
|
|
- Produce user-facing language.
|
|
- Make decisions — only describe state.
|
|
- Skip assessment because the turn appears "unimportant."
|
|
|
|
---
|
|
|
|
## Stage 5 — Behaviour Selection
|
|
|
|
### Purpose
|
|
|
|
Determine which expert facilitator behaviour to deploy based on the assessment from Stage 4. This is where the system moves from *describing* what is happening to *choosing* what kind of help to provide.
|
|
|
|
### Inputs
|
|
|
|
- State Assessment (all seven dimensions) from Stage 4.
|
|
- Inventory of available behaviours (14 patterns documented in `facilitator-behaviour.md`).
|
|
|
|
### Outputs
|
|
|
|
A selected behaviour and its intended effect on the investigation:
|
|
- The specific behaviour to deploy (Orient / Acknowledge / Observe pattern / Clarify / Validate / Connect / Challenge assumption / Refine understanding / Expose uncertainty / Decide direction / Pause / Avoid premature closure / Communicate confidence honestly / Progressively narrow focus).
|
|
- Confidence in the selection (high when multiple dimensions converge; moderate when signals are mixed).
|
|
|
|
### Must Never
|
|
|
|
- Reason about the investigation's content.
|
|
- Generate a question or response text directly.
|
|
- Bypass assessment and inspect the graph.
|
|
- Deploy a behaviour that the phase constrains against (e.g., Orient in Deepening phase).
|
|
- Select more than one primary behaviour per turn.
|
|
|
|
---
|
|
|
|
## Stage 6 — Conversation Response
|
|
|
|
### Purpose
|
|
|
|
Execute the selected behaviour through natural language. This is where abstract behavioural intention becomes a concrete, user-facing interaction.
|
|
|
|
### Inputs
|
|
|
|
- Selected behaviour and its intended effect from Stage 5.
|
|
- Current Narrative from Stage 3 (content to reference in the response).
|
|
- Investigation context (situation, history, what was just learned).
|
|
|
|
### Outputs
|
|
|
|
A conversational response that:
|
|
- Matches the selected behaviour's intent.
|
|
- Acknowledges what the user contributed.
|
|
- Advances the investigation along a coherent thread.
|
|
- Communicates confidence proportionally to evidence quality.
|
|
- Contains a clear next step if one is needed.
|
|
|
|
### Must Never
|
|
|
|
- Introduce content not supported by the narrative or graph.
|
|
- Ask a question that does not serve the selected behaviour.
|
|
- Overstate confidence in what is known.
|
|
- Understate confidence where evidence is strong.
|
|
- Respond to user input without first acknowledging it.
|
|
|
|
---
|
|
|
|
## Stage 7 — Workspace Projection
|
|
|
|
### Purpose
|
|
|
|
Render the current investigation state into visible UI panels so the user can see what is known, what remains uncertain, and how they arrived at this point. This is a passive projection — it shows but does not decide.
|
|
|
|
### Inputs
|
|
|
|
- Investigation Narrative from Stage 3.
|
|
- State Assessment from Stage 4 (for display labels like phase indicators).
|
|
- Behaviour Selection from Stage 5 (to contextualise the current interaction mode).
|
|
|
|
### Outputs
|
|
|
|
Panel projections including:
|
|
- Facilitator view (current understanding, active unknowns, what matters next).
|
|
- Investigation status (phase, progress signals, evidence quality).
|
|
- Situation and investigation map (reference artefacts, stable across turns).
|
|
- History (growing conversation log extending from the response).
|
|
|
|
### Must Never
|
|
|
|
- Generate content independently of the narrative.
|
|
- Display information that contradicts the assessment.
|
|
- Update based on behaviour selection — it shows state, not action intent.
|
|
- Re-implement graph-to-narrative translation.
|
|
|
|
---
|
|
|
|
## Stage 8 — Wait for Next Observation
|
|
|
|
### Purpose
|
|
|
|
Return control to the user. The turn is complete when the user sees their response reflected in the workspace and receives a conversation prompt that invites continued investigation.
|
|
|
|
### Inputs
|
|
|
|
Everything produced in previous stages, now rendered for user consumption.
|
|
|
|
### Outputs
|
|
|
|
Nothing system-generated. The next observation originates entirely from the user.
|
|
|
|
### Must Never
|
|
|
|
- Proceed to the next turn before the user responds.
|
|
- Auto-generate observations or continue without user input.
|
|
- Change the workspace state while waiting (beyond loading indicators).
|
|
|
|
---
|
|
|
|
## Implementation Status
|
|
|
|
| Stage | Description | Status | Experiment |
|
|
|-------|-------------|--------|------------|
|
|
| 1 | User Observation | Implemented (input) | — |
|
|
| 2 | Reasoning Graph Update | Implemented | Various |
|
|
| 3 | Investigation Narrative Update | Partially implemented | — |
|
|
| 4 | State Assessment | **Implemented** (v0.1) | Exp 18 |
|
|
| 5 | Behaviour Selection | Design only | **Exp 19 next** |
|
|
| 6 | Conversation Response | Design only | Post-Exp 19 |
|
|
| 7 | Workspace Projection | Implemented (UI) | Various |
|
|
| 8 | Wait for Next Observation | Implemented (state machine) | — |
|
|
|
|
Stages 4 and 5 remain as architectural specifications without executable code. Stage 4 was completed in Experiment 18; Stage 5 is the next implementation target.
|
|
|
|
---
|
|
|
|
## What This Turn Cycle Proves
|
|
|
|
The investigation turn cycle is not a new layer. It is an observation about how existing layers interact during a real investigation. It confirms that:
|
|
|
|
1. Every layer has a single responsibility.
|
|
2. Information flows downward through the architecture.
|
|
3. Feedback flows upward when the user provides a new observation.
|
|
4. No layer inspects another's implementation details.
|
|
5. The cycle is deterministic in structure but adaptive in content.
|
|
|
|
This document records what the investigation *does*, not how it is implemented.
|