Implement Experiment 19: deterministic behaviour selector with five
behaviours (Acknowledge, Clarify, Summarise, Continue, Pause).
- lib/behaviour-selection/behaviour-selector.js — Pure function selector
applying v0.1 rules in priority order (acknowledge > clarify > summarise >
pause > continue). Defaults to Continue with low confidence when no rule
matches or assessment is incomplete. Guards against partial objects.
- tests/behaviour-selector.test.js — 51 tests covering all five behaviours,
priority ordering, contract conformance, determinism, edge cases, and
scenario-based validation with mock investigations.
- docs/design-evolution-log.md — Close Experiment 18 (record what assessor
enabled for Behaviour Selection), add Experiment 19 section with hypothesis,
scope, evaluation criteria, and open questions.
Passive integration only: no changes to reasoning engine, prompts, graph
generation, decomposition, narrative generation, API contracts, UI behaviour,
or Ollama integration.
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).
Compress the speculative 452-line architecture spec into a constraint-focused
experiment brief. Reduce the initial behaviour set to five patterns
(Acknowledge, Clarify, Summarise, Continue, Pause) — the smallest useful
subset for testing whether behaviour selection improves over 'always ask'.
Remove: arbitrary weights/scores, convergence requirements, phase-constrained
tables (design preferences not discoveries), rationale output infrastructure,
Behaviour Readiness dimension specs.
Keep: five behaviours with plain condition-matching rules, explicit v0.1 scope
boundary, Future Considerations section for deferred architecture items.
Also add Behaviour Selection entry to reasoning-contract-backlog and mark
Stage 4 (State Assessment) as implemented in investigation-turn-cycle.
Close Experiment 15 (Facilitator Behaviour Specification).
Introduce Experiment 16 — Investigation State Assessment.
- Create docs/investigation-state-assessment.md with 7 assessment dimensions:
Current Investigation Phase, Investigation Progress, Evidence Quality,
Understanding Trajectory, Uncertainty Trend, Conversation Health,
and Behaviour Readiness. Each dimension includes purpose, observable
signals, possible values, and how behaviours may consume it.
- Document 6 assessment principles (Assess Not Decide, All Signals
Traceable to Narrative, Descriptive Not Prescriptive, Convergence Over
Single Signal, Stateful Across Turns, Uncertainty About Assessment Is
Itself Assessable).
- Include exploratory decision matrix linking investigation states to
likely behaviours with reasons.
- Prepend Behaviour Selection section to docs/facilitator-behaviour.md
recording that behaviours are selected from Investigation State
Assessment and do not inspect graph nodes directly.
- Update docs/design-evolution-log.md: close Experiment 15, add
Experiment 16 closure, record emerging architecture with the new layer
between Narrative and Behaviour Selection.
No implementation. Documentation only. No changes to reasoning engine,
graph generation, prompts, orchestrator, APIs, Ollama integration, or UI.
- Create docs/facilitator-behaviour.md: behavioural specification of the
Confidence Engine with 14 identified behaviours (Orient, Acknowledge,
Observe pattern, Clarify, Validate, Connect, Challenge assumption, Refine
understanding, Expose uncertainty, Decide direction, Know when to pause,
Avoid premature closure, Communicate confidence honestly, Progressively
narrow focus).
- Update docs/design-evolution-log.md: add Experiment 15 entry documenting
what Experiment 14 proved, what emerged (the gap is behavioural not visual),
and why the next phase focuses on conversation behaviour over UI.
- Update .claude/ux-guidelines.md: add Facilitator Behaviour section with
core behavioural principles, anti-patterns, state-aware selection criteria,
and architecture relationship.
No code changes — this is a behavioural specification for future implementation.
Emphasise the active investigation card through stronger elevation,
clearer borders, and improved spacing. Quiet supporting panels by
reducing border opacity, softening heading weight, and lowering
text contrast — making them available without competing for attention.
Facilitator card receives a warm surface tint to read as a briefing
card rather than a generic panel.
Documentation: close experiment 05 with findings, add experiment 06
to the design evolution log, add Attention Hierarchy to UX guidelines,
defer dark mode to a future Investigation Mode experiment.
Presentation changes only — no reasoning, prompts, graph, API, or
backend modifications.
Phase 2: Recovery state components (ProviderUnavailableCard,
MalformedResponseCard, UnexpectedStateCard, ContinueLaterBanner) with
automatic error detection for provider/network/malformed/unexpected states.
Phase 3: Session persistence via sessionStorage — save after each
successful turn, restore on mount, clear on restart/reset. Continuelater banner shown when session is restored.
Phase 4: InvestigationSummaryPanel component displaying current status,
understanding summary, questions answered/remaining, investigation timestamps.
Phase 5: docs/reasoning-contract-backlog.md documenting all mocked
fields (60+ rows across 7 categories) with feature/UI need/mock/desired
output/stage/notes columns.
Also: wired onRestart through ReasoningWorkspace → ScenarioForm, fixed
getErrorType scope issues, removed broken window.__restartInvestigation.
robbond