docs: narrow behaviour-selection to v0.1 implementation brief
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.
This commit is contained in:
@@ -146,6 +146,103 @@ The current adapter (`lib/map/investigation-map-adapter.js`) uses generic placeh
|
||||
|
||||
---
|
||||
|
||||
## Behaviour Selection (Experiment 19)
|
||||
|
||||
**Goal:** Test whether selecting from a small set of behaviours — instead of always asking a question — makes the investigation feel like guided thinking rather than automated Q&A.
|
||||
|
||||
### v0.1 Behaviour Set (5 Patterns)
|
||||
|
||||
| Behaviour | When to deploy | What it does |
|
||||
|-----------|---------------|--------------|
|
||||
| **Acknowledge** | Any turn where user provided useful info (≥1 resolved node) | State what was learned; do not immediately ask |
|
||||
| **Clarify** | Conversation health is `too_broad` OR phase is `orienting` with insufficient data | Ask for a single specific piece of context |
|
||||
| **Summarise** | Phase is `synthesising`/`concluding`; or ≥3 turns without summarisation | Restate current understanding; compress without losing detail |
|
||||
| **Continue** | Default — no other behaviour matches | Ask the next useful question (current engine behaviour) |
|
||||
| **Pause** | Phase is `focusing` with stalled progress | Hold space; acknowledge what was learned; invite reflection |
|
||||
|
||||
### Selection Rules (No Scoring, No Weights)
|
||||
|
||||
Plain conditions. If multiple fire, priority is: Acknowledge > Clarify > Summarise > Pause > Continue.
|
||||
|
||||
1. Acknowledge if conversation health is healthy AND at least one node resolved
|
||||
2. Clarify if conversation health is too_broad OR phase is orienting with <3 observations
|
||||
3. Summarise if phase is synthesising/concluding OR ≥3 turns without summarisation
|
||||
4. Pause if phase is focusing AND progress is stalled
|
||||
5. Continue as default
|
||||
|
||||
### Why v0.1 Is Deliberately Narrow
|
||||
|
||||
- No scoring or weighting (invented numbers, not observed signals)
|
||||
- No convergence requirements (design preference, not discovery)
|
||||
- Only the three assessment dimensions currently available (phase, progress, conversation health)
|
||||
- One behaviour per turn — no combinations, no stable pairing
|
||||
- No rationale output or developer view infrastructure (signal first, display later)
|
||||
|
||||
### Future Considerations (Not In v0.1)
|
||||
|
||||
See `docs/behaviour-selection.md` section "Future Considerations" for: signal weighting, convergence thresholds, full 14-behaviour inventory, Behaviour Readiness derived dimension, rationale output.
|
||||
|
||||
---
|
||||
|
||||
## Investigation State Assessment (Experiment 18)
|
||||
|
||||
The investigation state assessment layer introduces three new assessed dimensions that feed into behaviour selection: **phase**, **progress**, and **conversationHealth**. Each dimension has its own value enum, confidence level, descriptive signals, and evidence object. The overall assessment uses the minimum confidence across all dimensions.
|
||||
|
||||
### Phase Assessment
|
||||
|
||||
| Feature | UI need | Temporary mock | Desired reasoning output | Likely stage | Notes |
|
||||
|---------|---------|---------------|------------------------|-------------|-------|
|
||||
| Behaviour Selection (phase gate) | Determine which behaviours are appropriate now | Heuristic based on resolved node count + hasActiveQuestion | `assessment.phase: { value, confidence, signals[], evidence }` where value ∈ `"orienting"`, `"exploring"`, `"focusing"`, `"deepening"`, `"synthesising"`, `"concluding"`, `"cannot_determine"` | Per-turn assessment | Deterministic thresholds: conclusive (active=0, resolved≥2), synthesising (active≤1, ratio>0.5), focusing (active=1, observations≥3), exploring (observations≥2, ratio<0.4), deepening (active>1, resolved≥3) |
|
||||
|
||||
### Progress Assessment
|
||||
|
||||
| Feature | UI need | Temporary mock | Desired reasoning output | Likely stage | Notes |
|
||||
|---------|---------|---------------|------------------------|-------------|-------|
|
||||
| Behaviour Selection (urgency gate) | Determine whether investigation is moving forward and at what velocity | Heuristic based on resolved count trend | `assessment.progress: { value, confidence, signals[], evidence }` where value ∈ `"accelerating"`, `"steady"`, `"stalled"`, `"looping"`, `"spiralling"`, `"cannot_determine"` | Per-turn assessment | Single-snapshot approximation in v0.1 using resolution ratio thresholds: accelerating (>0.6), steady (0.2-0.6), stalled (<0.2 with ≥1 resolved) |
|
||||
|
||||
### Conversation Health Assessment
|
||||
|
||||
| Feature | UI need | Temporary mock | Desired reasoning output | Likely stage | Notes |
|
||||
|---------|---------|---------------|------------------------|-------------|-------|
|
||||
| Behaviour Selection (interruption gate) | Determine whether the interaction pattern needs adjustment regardless of investigation state | Heuristic based on question type and unknown count | `assessment.conversationHealth: { value, confidence, signals[], evidence }` where value ∈ `"healthy"`, `"repetitive"`, `"too_broad"`, `"too_narrow"`, `"user_overloaded"`, `"user_under_informed"`, `"cannot_determine"` | Per-turn assessment | v0.1 rules: healthy (has unknown + has question), too_broad (>3 active, <2 resolved), too_narrow (≤1 observation with question) |
|
||||
|
||||
### Confidence Aggregation
|
||||
|
||||
| Feature | UI need | Temporary mock | Desired reasoning output | Likely stage | Notes |
|
||||
|---------|---------|---------------|------------------------|-------------|-------|
|
||||
| Overall assessment trustworthiness | How much should we trust any individual dimension? | N/A — no prior equivalent | `assessment.confidence` = min(phase.confidence, progress.confidence, conversationHealth.confidence) where "high" < "medium" < "low" < "cannot_determine" | Per-turn assessment | Conservative: if ANY dimension is low/cannot_determine, overall drops. This prevents false precision in behaviour selection. |
|
||||
|
||||
### Evidence Objects (Source Mapping)
|
||||
|
||||
All evidence fields are derived from the situation graph and orchestrator diagnostics without direct graph traversal by the behaviour layer:
|
||||
|
||||
| Evidence Field | Source | Available In |
|
||||
|---------------|--------|-------------|
|
||||
| `resolvedNodeCount` | count of nodes with status `"resolved"` or in `resolvedNodeIds` | Every turn |
|
||||
| `activeUnknownCount` | count of unknown-kinded unresolved nodes + active node fallback | Every turn |
|
||||
| `unknownResolutionRatio` | resolvedNodeCount / totalNonEmptyNodes (null if total ≤ 0) | Every turn |
|
||||
| `observationDensity` | observations = observation-kind known/resolved + high-confidence non-unknown non-state | Every turn |
|
||||
| `evidenceDepth` | `"shallow"` (<2), `"moderate"` (2-3), `"deep"` (≥4 observations) | Every turn |
|
||||
| `turnCount` | approximated as `floor(totalNodes / 3)` | Every turn |
|
||||
| `hasActiveQuestion` | Boolean: `selectedQuestion?.nodeId` exists | Every turn |
|
||||
| `summaryLength` | Length of `situationGraph.currentSummary` | Every turn |
|
||||
|
||||
### Current Limitations (Experiment 18 v0.1)
|
||||
|
||||
These are acknowledged constraints of the current implementation, not change requests:
|
||||
|
||||
- **Single-snapshot progress**: v0.1 uses a resolution ratio from the current snapshot only. Multi-turn trend detection (looping, spiralling) is planned but requires turn history data not yet available in the contract.
|
||||
- **No evidence quality dimension**: This is specified in the architecture doc but requires per-node evidence confidence scoring across multiple sources — not yet implementable.
|
||||
- **No understanding trajectory dimension**: Requires comparing narrative complexity across turns; depends on future narrative evolution.
|
||||
- **No uncertainty trend dimension**: Requires tracking which unknowns resolve by what pattern across turns.
|
||||
- **No behaviour readiness layer**: The final synthesis of all dimensions into behaviour signals is deferred to the behaviour selection experiment.
|
||||
|
||||
### Implementation Status
|
||||
|
||||
**Implemented.** The assessor (`lib/assessment/investigation-state-assessor.js`) produces a deterministic assessment object matching this contract at v0.1 schema version. Integration call sites in `lib/graph/orchestrator.js` (lines ~552, ~904, ~1013) pass correctly shaped input to `assessInvestigationState()`. The 51-test suite validates all classification rules and edge cases.
|
||||
|
||||
---
|
||||
|
||||
## Facilitator View Projection (Experiment 12)
|
||||
|
||||
Version C derives its content from existing graph fields without requiring new backend data. The following fields are used as inputs:
|
||||
|
||||
Reference in New Issue
Block a user