confidence-engine/docs/task-context-packs.md

# Task-Specific Context Packs — Confidence Engine

> Routes future sessions to the minimal reading list for each task type. Choose exactly one pack. Add one document at a time only when a named gap requires it. Record why each additional document was loaded.

## Pack 1 — Engine Experiment Work

### Always read
- `docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md` (methodology continuity — required before any reasoning development)
- `docs/current-handoff.md` (current state, Git checkpoint, experiment log)
- `docs/current-working-principles.md`
- `.claude/architecture-guardrails.md`
- `docs/current-implementation-verification.md`

### First document to read for Confidence Engine reasoning work:
**`docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md`** — the durable methodology anchor. Do not load experiment apparatus before this document. A new session must understand the method before examining recent technical experiments.

### Then read only when relevant
- the specific implementation file;
- its focused tests;
- the immediately previous experiment entry in `docs/design-evolution-log.md`;
- the relevant contract or backlog entry.

### Do not load by default
- full design-evolution history; archived documents; UI mock reference; unrelated architecture documents.

### Stop and ask or record a gap when
- current documentation and source disagree;
- the task requires an undocumented contract;
- the experiment begins expanding into several capabilities;
- you cannot describe the reasoning operation in Confidence Engine methodology terms (could a trained human facilitator perform it without an LLM?).

### Live experiment execution route

A canonical live-update harness exists at `tests/graph/live-update-experiment-helper.cjs`.
It loads `.env.local`, validates required variables, invokes the real `updateCase()` production
entry point, and returns standard reasoning checkpoints (userSupportedMeaning, possibleInference,
rawAnswerCategory, proposedMeaningCategory, proposalValidation, compatibilityGuard, graphMutation,
selectedQuestion, behaviourSelection, reasoningState).

**Execution pattern:**

```js
const { runLiveExperiment } = require("./tests/graph/live-update-experiment-helper.cjs");

const result = await runLiveExperiment({
  graph: /* SituationGraph fixture *\/,
  previousQuestion: "Is risk a hard constraint?",
  answer: "Risk matters more to me.",
});

// Checkpoints available on `result`:
//   result.userSupportedMeaning
//   result.possibleInference
//   result.rawAnswerCategory
//   result.proposedMeaningCategory
//   result.proposalValidation
//   result.compatibilityGuard
//   result.graphMutation
//   result.selectedQuestion
//   result.behaviourSelection
//   result.reasoningState
```

**Required environment (from `.env.local`):**
- `process.env.OLLAMA_BASE_URL` — must be a real host (no localhost fallback)
- `process.env.OLLAMA_MODEL` — model name (e.g. `qwen-claude:latest`)

The harness fails clearly if either variable is missing or OLLAMA_BASE_URL points to localhost.
It makes exactly one live Ollama call per invocation unless the experiment explicitly specifies otherwise.

**Rule:** During normal reasoning experiments, never create a bespoke harness, enumerate `/api/tags`,
probe localhost, or discover/substitute another model. Use the canonical harness above.

### Canonical live multi-turn product-observation route

A minimal script exists at `scripts/reproduce-multi-turn-investigation.mjs`.

**Execution pattern:**

```bash
# 1. Start dev server
npx next dev

# 2. Run multi-turn script (requires running dev server)
node scripts/reproduce-multi-turn-investigation.mjs
```

**State-chaining rule:**

- Start returns `situationGraph` + `selectedQuestion.question`
- Update 1 input: `situationGraph` from start, `previousQuestion` = selected question; receives `updatedSituationGraph` as next graph
- Update 2 input: `updatedSituationGraph` from update 1, `previousQuestion` = update 1's selected question
- Each returned `selectedQuestion.question` becomes the next `previousQuestion`
- If any call fails, that is enough to establish the route up to that failure — do not work around it

**Maximum natural live calls:** 3 (start: 1, update 1: 1, update 2: 1)

## Pack 2 — UI and Mock Work

### Always read
- `docs/current-project-state.md`
- `docs/current-working-principles.md`
- `.claude/architecture-guardrails.md`
- `docs/ui-mock-reference.md`

### Then read only when relevant
- the affected component; its focused tests;
- the relevant UX guideline section;
- the named mock fixture.

### Do not load by default
- deferred UX backlog; archived UI reports; engine classifier documents; full design-evolution history.

## Pack 3 — Architecture or Contract Review

### Always read
- `docs/current-project-state.md`
- `docs/current-implementation-verification.md`
- `.claude/architecture-guardrails.md`
- `docs/current-working-principles.md`

### Then read only when relevant
- the named contract;
- `docs/architectural-principles.md`;
- the implementation files needed to verify the contract;
- a named historical experiment only when provenance matters.

### Important warning
Aspirational architecture must not be described as current implementation.

## Pack 4 — Knowledge-Management Work

### Always read
- `docs/current-project-state.md`
- `docs/project-knowledge-inventory.md`
- `docs/task-context-packs.md`
- `.claude/project-context.md`

### Then read only when relevant
- the document being reviewed;
- `docs/archive/README.md`;
- the immediately previous knowledge-management experiment.

### Do not load by default
- source code; tests; archived document contents; unrelated product or architecture documents.

## Common Rules

1. Start with the smallest pack.
2. Add one document at a time only when a named gap requires it.
3. Record why additional context was loaded.
4. Do not silently open the full experiment history.
5. Prefer named headings over fixed line numbers.
6. Source code decides what is implemented.
7. Current-state documents decide normal routing.
8. Historical documents explain how the project arrived there.
9. Leave a Return-to-Work Note after every completed experiment.

## Routing Test A — Engine Task

**Task:** Verify whether Behaviour Selection currently affects the user-facing response.

**Documents selected:** `docs/current-project-state.md`, `docs/current-implementation-verification.md`, `.claude/architecture-guardrails.md`.

**Documents excluded:** source code, full history, archived documents, UI mock reference.

**Sufficient?** Yes. current-implementation-verification.md §3b states Behaviour Selection has no callers outside its own module; current-project-state §3 classifies it as isolated. No extra file required.

## Routing Test B — UI Task

**Task:** Choose the correct mock scenarios for testing a long investigation and contradictory evidence.

**Documents selected:** `docs/ui-mock-reference.md`, `docs/current-project-state.md`, `docs/task-context-packs.md`.

**Documents excluded:** deferred UX backlog, engine classifier documents, full history.

**Deferred UX backlog needed?** No. `docs/ui-mock-reference.md` is the UI and Mock pack entry document; scenario names ("Long investigation (10–15 turns)" and "Contradiction") and usage guidance come from it. It is part of this pack's routing, not an addition. No extra file required.

---

*Created by Experiment 33. Branch: feature/user-workspace-ux-v0.7. Engine and UI experiments remain paused.*