architecture: define investigation turn cycle

2026-08-05 16:14:22 +01:00
parent cb0c779019
commit e44785365c
5 changed files with 1032 additions and 1 deletions
@@ -0,0 +1,270 @@
+# 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).
+
+---
+
+## 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.