182 lines
7.5 KiB
Markdown
182 lines
7.5 KiB
Markdown
# 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-working-principles.md` §0 (Axiomatic Principles A1–A12 — durable methodology baseline)
|
||
- `docs/Confidence_Engine_Return_to_Origin_Methodology_Context_2026-08-18.md` (methodology continuity, RTO evidence)
|
||
- `docs/current-handoff.md` (current operational state, evidence semantics, settled boundaries)
|
||
- `.claude/architecture-guardrails.md`
|
||
- `docs/current-implementation-verification.md`
|
||
|
||
### First document to read for Confidence Engine reasoning work:
|
||
**`docs/current-working-principles.md` §0** — the axiomatic principles. All future work must be evaluated against A1–A12 before any experiment or implementation consideration. Do not load experiment apparatus before these axioms and the RTO methodology context.
|
||
|
||
### Then read only when relevant
|
||
- the specific implementation file;
|
||
- its focused tests;
|
||
- the design evolution archive index at `docs/design-evolution/README.md` when provenance is needed;
|
||
- the relevant contract or backlog entry.
|
||
|
||
### Do not load by default
|
||
- the full experiment 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.*
|