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/current-project-state.md
• docs/current-working-principles.md
• .claude/architecture-guardrails.md
• docs/current-implementation-verification.md

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.

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:

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.

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.