# 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.