experiment: create task-specific context packs

2026-08-06 15:30:14 +01:00
parent 51f0c11bc8
commit b959cfa7a7
5 changed files with 176 additions and 0 deletions
@@ -106,3 +106,5 @@ For UI mock work, read `docs/ui-mock-reference.md`. Do not load
 `docs/archive/deferred-ux-backlog.md` unless a named past UX idea is being reviewed.
 Engine and UI experiments are paused. First file to inspect when resuming:
 `docs/current-project-state.md`, then `docs/project-knowledge-inventory.md`.
+
+> After reading `docs/current-project-state.md`, choose the relevant minimal pack from `docs/task-context-packs.md`. Do not combine packs unless a specific task genuinely crosses boundaries.
@@ -90,6 +90,7 @@ The following were built during Experiments 18–25B. They are isolated diagnost
 | Product direction and stage | `.claude/project-context.md` |
 | Task-specific or historical references | `docs/project-knowledge-inventory.md` |
 | Broader architectural intent | `docs/architectural-principles.md` (task-specific only) |
+| Task-specific routing by work type | `docs/task-context-packs.md` (four minimal packs + common rules) |
 | Historical evidence or a named experiment | `docs/design-evolution-log.md` (the named section only) |

 Do not read the full design-evolution log unless a specific experiment is required. Use the inventory to locate task-specific context, then load only what you need.
@@ -112,6 +113,10 @@ The current-state briefing was checked against source code via targeted code ins

 Current principles now live in `docs/current-working-principles.md`. This short document contains only guidance supported by verified implementation, current project direction, and established product philosophy — organised into three sections: user experience, reasoning, and building the system. Broader and aspirational architecture remains in `docs/architectural-principles.md` as a task-specific reference; it has not been rewritten or deleted. Future sessions should use `docs/current-working-principles.md` by default for product and reasoning work. Engine and UI experiments remain paused after Experiment 25B. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `docs/current-project-state.md`, then `docs/current-working-principles.md` for current guidance.

+### Return-to-Work Note (Experiment 33)
+
+Task-specific context packs now exist in `docs/task-context-packs.md`, giving each work type a minimal four-document starting set plus targeted reading paths. Future sessions should start with `docs/current-project-state.md`, then choose one pack from `docs/task-context-packs.md`. Additional documents should be loaded only for a named gap, with the reason recorded. Engine and UI experiments remain paused. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `docs/current-project-state.md`, then select the relevant pack from `docs/task-context-packs.md`.
+
 ## Verification Marker

 Implementation status last checked against source: Experiment 28.
@@ -1952,3 +1952,55 @@ Pending Rob's review. No source code or tests changed. Engine and UI experiments
 Current principles now live in `docs/current-working-principles.md`. This short document contains only guidance supported by verified implementation, current project direction, and established product philosophy — organised into three sections: user experience, reasoning, and building the system. Broader and aspirational architecture remains in `docs/architectural-principles.md` as a task-specific reference; it has not been rewritten or deleted. Future sessions should use `docs/current-working-principles.md` by default for product and reasoning work. Engine and UI experiments remain paused after Experiment 25B. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `docs/current-project-state.md`, then `docs/current-working-principles.md` for current guidance.

 ---
+
+## Experiment 33 — Create Task-Specific Context Packs
+
+**Branch:** `feature/user-workspace-ux-v0.7`
+
+### Hypothesis
+
+A single concise context-pack guide can give each task type a minimal reading list, clear exclusions, and a stopping rule — reducing unnecessary context loading while preserving access to deeper material when a specific gap appears.
+
+### Source Documents Used
+
+- `docs/current-project-state.md` — Context Loading Guide; Current Engine Capabilities; Work Currently Paused
+- `docs/project-knowledge-inventory.md` — Current Working Context; Task-Specific References
+- `docs/current-implementation-verification.md` — Active Capabilities; Passive or Isolated Capabilities
+- `docs/current-working-principles.md` — entire file
+- `docs/ui-mock-reference.md` — headings and routing information only
+- `.claude/project-context.md` — routing notes only
+- `.claude/architecture-guardrails.md` — headings only
+- Experiment 32 entry in `docs/design-evolution-log.md` (lines 1895–1948)
+
+### Deliverable
+
+Created `docs/task-context-packs.md` (~110 lines) with four packs:
+- **Pack 1 — Engine Experiment Work:** current-project-state, current-working-principles, architecture-guardrails, current-implementation-verification.
+- **Pack 2 — UI and Mock Work:** current-project-state, current-working-principles, architecture-guardrails, ui-mock-reference.
+- **Pack 3 — Architecture or Contract Review:** current-project-state, current-implementation-verification, architecture-guardrails, current-working-principles + aspirational warning.
+- **Pack 4 — Knowledge-Management Work:** current-project-state, project-knowledge-inventory, task-context-packs, project-context.
+
+Each pack lists what to always read, what to read only when relevant, and what to not load by default. Common rules prevent silent context inflation. Two routing tests verify sufficiency without loading history or source code.
+
+### Routing Test A — Engine Task
+
+**Task:** Verify whether Behaviour Selection currently affects the user-facing response.
+**Result:** Pack sufficient. `docs/current-implementation-verification.md` §3b states "Called by: None" for Behaviour Selection; `docs/current-project-state.md` §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.
+**Result:** Pack sufficient. `docs/ui-mock-reference.md` lists "Long investigation (10–15 turns)" and "Contradiction" with matching purposes. Deferred UX backlog not needed.
+
+### Validation
+
+- All referenced files exist; no pack relies on fixed line numbers.
+- Each pack has a smaller default context than the full project documentation.
+- Active and passive capabilities remain clearly separated.
+- No source code or tests changed; no files moved or deleted.
+
+### Return-to-Work Note
+
+Task-specific context packs now exist in `docs/task-context-packs.md`, giving each work type a minimal four-document starting set plus targeted reading paths. Future sessions should start with `docs/current-project-state.md`, then choose one pack from `docs/task-context-packs.md`. Additional documents should be loaded only for a named gap, with the reason recorded. Engine and UI experiments remain paused. Branch: `feature/user-workspace-ux-v0.7`. First file to inspect when resuming: `docs/current-project-state.md`, then select the relevant pack from `docs/task-context-packs.md`.
+
+---
@@ -47,6 +47,12 @@ These are the documents Claude should normally read before continuing Confidence
 - **Why required:** Self-referential — use it as a loading checklist.
 - **Size:** small

+### docs/task-context-packs.md (new — Experiment 33)
+- **Purpose:** Task-specific routing — four minimal context packs, common rules, and two routing tests proving each pack's sufficiency. Serves as the task-routing entry point after reading current-project-state.md.
+- **Sections to read:** The pack matching your work type; Common Rules; relevant routing test for confidence.
+- **Why required:** Provides a smaller starting context than the full inventory. Eliminates ambiguity about which documents to open first for each work type.
+- **Size:** small (~110 lines)
+
 ### docs/03_Confidence_Engine_Language_Guide.md
 - **Purpose:** Exact language rules for user-facing output (voice, translations, what to avoid).
 - **Sections to read:** Entire file (~27 lines).
@@ -107,6 +113,7 @@ Grouped by task domain. Only load the group relevant to your work.
 | Document | Purpose | Loaded When |
 |---|---|---|
 | `docs/document-role-review.md` (140 lines) | Classification of deferred documents; practical routing test for UI mock and reasoning tasks | When reviewing which documents to load; when a task involves architectural guidance or mock fixture reference |
+| `docs/task-context-packs.md` (~110 lines) | Task-routing entry point — four minimal packs for engine, UI, architecture review, and knowledge management work | Always for any new task — determines which pack to follow first |

 ### Testing and contracts
 | Document | Purpose | Loaded When |
@@ -0,0 +1,110 @@
+# 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.
+
+## 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. The mock reference already lists "Long investigation (10–15 turns)" and "Contradiction" with purposes matching the task. No extra file required.
+
+---
+
+*Created by Experiment 33. Branch: feature/user-workspace-ux-v0.7. Engine and UI experiments remain paused.*