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).
9.5 KiB
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:
- Current Investigation Phase — Orienting / Exploring / Focusing / Deepening / Synthesising / Concluding
- Investigation Progress — Accelerating / Steady / Stalled / Looping / Spiralling
- Evidence Quality — Weak / Mixed / Strong / Contradictory
- Understanding Trajectory — Growing / Static / Confused / Consolidating
- Uncertainty Trend — Increasing / Reducing / Stable / Asymmetric
- Conversation Health — Healthy / Repetitive / Too broad / Too narrow / User overloaded / User under-informed
- 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:
- Every layer has a single responsibility.
- Information flows downward through the architecture.
- Feedback flows upward when the user provides a new observation.
- No layer inspects another's implementation details.
- The cycle is deterministic in structure but adaptive in content.
This document records what the investigation does, not how it is implemented.