confidence-engine/docs/investigation-state-assessment-contract.md

Investigation State Assessment Contract

Architecture Experiment 18 — First Executable Slice

This document defines the data contract for the investigation state assessment layer. It is the interface between investigation narrative (Stage 3) and behaviour selection (Stage 5).

---

Versioning

{
  "version": "v0.1",          // Schema version — increment only on field additions/removals
  "assessedAt": "ISO-8601",   // When this assessment was computed
  "confidence": "high|medium|low" // Overall assessment confidence
}

All fields below are part of the v0.1 contract. Adding new fields requires a version bump to v0.2+. Removing or renaming existing fields also requires a version bump.

---

Assessment Object Shape

Phase

Evaluates where the investigation is in its lifecycle.

{
  "phase": {
    "value": "orienting|exploring|focusing|deepening|synthesising|concluding|cannot_determine",
    "confidence": "high|medium|low",
    "signals": [string],   // Descriptive reasons for the classification
    "evidence": {           // What data supported this classification
      "resolvedNodeCount": number,
      "activeUnknownCount": number,
      "unknownResolutionRatio": number | null,
      "observationDensity": number | null,
      "evidenceDepth": string | null  // "shallow|moderate|deep"
    }
  }
}

Progress

Tracks whether understanding is advancing, stalled, or regressing.

{
  "progress": {
    "value": "accelerating|steady|stalled|looping|spiralling|cannot_determine",
    "confidence": "high|medium|low",
    "signals": [string],
    "evidence": {
      "turnCount": number,
      "recentResolutionsLastTurn": number,
      "newUnknownsPerTurn": number | null,
      "repeatedNodeIds": string[]   // Nodes appearing across 3+ turns without resolution
    }
  }
}

Conversation Health

Evaluates whether the conversation pattern is productive.

{
  "conversationHealth": {
    "value": "healthy|repetitive|too_broad|too_narrow|user_overloaded|user_under_informed|cannot_determine",
    "confidence": "high|medium|low",
    "signals": [string],
    "evidence": {
      "questionTypeDistribution": Record<string, number> | null,  // reasoningPattern -> count
      "activeUnknownCount": number,
      "resolvedNodeRatio": number | null,
      "hasActiveQuestion": boolean | null,
      "summaryLength": number | null
    }
  }
}

Overall Assessment

All dimensions combined:

{
  "version": "v0.1",
  "assessedAt": "ISO-8601",
  "confidence": "high|medium|low",
  "phase": { ... },
  "progress": { ... },
  "conversationHealth": { ... }
}

---

Deterministic Rules (Phase)

The phase classifier uses conservative thresholds and defaults to cannot_determine when data is insufficient.

Values

Phase	Classification Rule
concluding	activeUnknownCount === 0 AND resolvedNodeCount >= 2 AND hasActiveQuestion === false — investigation has reached terminal state
synthesising	activeUnknownCount <= 1 AND resolvedNodeRatio > 0.5 — near completion, synthesis possible
focusing	activeUnknownCount === 1 AND knownObservations >= 3 — single remaining unknown with sufficient context
exploring	observationCount >= 2 AND unknownResolutionRatio < 0.4 — gathering initial evidence
orienting	observationCount < 2 OR totalNodeCount < 3 — insufficient structure to classify
deepening	Residual: activeUnknownCount > 1 AND resolvedNodeCount >= 3 — structured investigation with remaining unknowns
cannot_determine	Insufficient data for any of the above classifications

Thresholds (Conservative)

• A node is "known" only if kind === "observation" OR (kind !== "unknown" AND status !== "provisional").
• An unknown is "active" only if kind === "unknown" AND status is not "resolved".
• Resolution ratio = resolvedNodeCount / totalNonEmptyNodeCount (null if total is 0).
• Known observation density threshold: ≥3 observations before classifying as focusing or above.

---

Deterministic Rules (Progress)

Progress uses a single-snapshot approximation for this first slice. Multi-turn history tracking is reserved for a future version.

Values

Progress	Classification Rule
accelerating	unknownResolutionRatio > 0.6 — resolving unknowns faster than they accumulate
steady	unknownResolutionRatio > 0.2 AND unknownResolutionRatio <= 0.6 — balanced progress
stalled	unknownResolutionRatio < 0.2 AND resolvedNodeCount >= 1 — some work done but no momentum
looping	repeatedNodeIds.length > 0 (nodes appearing across turns) AND resolvedNodeCount === 0 for those nodes
spiralling	newUnknownsPerTurn > resolvedNodeCount for recent history (requires turn history)
cannot_determine	resolvedNodeCount === 0 AND totalNodeCount <= 2 — no sufficient data yet

Thresholds (Conservative)

• Resolution ratio = resolvedNodeCount / totalNonEmptyNodeCount.
• No progress classification is assigned below 1 resolved node.
• If resolution ratio cannot be computed (total === 0 or all nodes unresolved), return cannot_determine.

---

Deterministic Rules (Conversation Health)

Conversation health evaluates the interaction pattern from available graph signals.

Values

Health	Classification Rule
healthy	Has active unknown AND has active question AND resolution ratio between 0 and 0.9
repetitive	Same reasoning pattern appears in >50% of questions (requires historical data)
too_broad	Multiple active unknowns (>3) without sufficient resolved context (<2 resolved)
too_narrow	Single observation with single unknown and no edges connecting them
user_overloaded	Active unknown count > 4 (exceeds working memory limit)
user_under_informed	Total observations < 2 AND active question exists (asking without enough context)
cannot_determine	Insufficient graph signals to evaluate conversation pattern

Thresholds (Conservative)

• "Has active unknown" = activeUnknownCount > 0.
• "Has active question" = selectedQuestion !== null.
• Resolution ratio for healthy = between 0 and 0.9 (not terminal, not empty).

---

Confidence Rules

Overall Confidence

The overall confidence is the minimum of all dimension confidences. If any dimension cannot be determined, overall confidence is "low".

Per-Dimension Confidence

Confidence	Condition
high	Classification supported by ≥2 independent signals AND data is complete (no null evidence fields)
medium	Classification supported by 1 signal AND data is mostly complete (≤1 null evidence field)
low	Classification supported by partial data OR has null evidence fields >1

---

What This Contract Must Never Do

• Never invent signals. Only use data actually present in the graph schema, orchestrator diagnostics, or facilitator-view outputs.
• Never reach false precision. When data is ambiguous, return cannot_determine rather than a confident but unsupported classification.
• Never mutate input state. This is a pure function — no side effects, no writes, no network calls.
• Never bypass the narrative layer. Assessment reads from narrative output and graph data, never directly from raw user input.
• Never prescribe behaviour. Assessment describes state only; interpretation belongs to behaviour selection.

---

Supported Data Sources (v0.1)

Source	Fields Available
situationGraph.nodes[]	id, label, description, kind, status, confidence, evidenceIds, dependsOn, affects
situationGraph.resolvedNodeIds[]	Array of resolved node IDs
situationGraph.activeUnknownNodeId	Nullable string — currently targeted unknown
selectedQuestion	{ nodeId, question, reason } nullable
diagnostics.reasoningPattern	Current turn's reasoning pattern key
diagnostics.nodeCount	Total node count
diagnostics.edgeCount	Total edge count
facilitatorView._meta	isTerminal, hasUnresolvedUnknowns, totalObservations, unresolvedUnknownsCount

---

Unsupported Signals (Planned for Future Versions)

These signals are specified in the investigation-state-assessment architecture document but require data not yet available in v0.1:

• Evidence Quality — requires per-node evidence confidence scoring across multiple sources
• Understanding Trajectory — requires comparing narrative complexity across turns
• Uncertainty Trend — requires tracking which unknowns are resolved and by what pattern
• Behaviour Readiness — requires mapping assessment output to behaviour inventory

These are tracked in reasoning-contract-backlog.md.

---

Recording Note

This contract was drafted for Experiment 18's first executable slice. It captures the minimal viable assessment object shape derived from actual repository data contracts (schema.js, orchestrator.js, facilitator-view-adapter.js). Future experiments will add dimensions and signals as the graph schema and diagnostics evolve.