confidence-engine/docs/project-knowledge-inventory.md

# Project Knowledge Inventory

> Created by Experiment 26. This document maps which documentation Claude needs to read for typical tasks, and which documents are best left unloaded unless specifically relevant.

## How to Use This Inventory

When beginning a task, load only the **Current Working Context** set below — plus any **Task-Specific References** that match your domain. Everything else is preserved but not loaded by default.

---

## 1. Current Working Context

These are the documents Claude should normally read before continuing Confidence Engine work. They answer: what does this product do? where are we now? how should we behave?

### .claude/project-context.md
- **Purpose:** Product direction, current development stage, core promise, and working philosophy.
- **Sections to read:** Entire file (~97 lines).
- **Why required:** It states what the Confidence Engine is, what product direction is active (v0.7 UX), and when not to resume broad reasoning architecture work. This single document answers more questions than any other.
- **Size:** small

### .claude/architecture-guardrails.md
- **Purpose:** Hard boundaries for UI/UX tasks; invariant rules for the reasoning engine.
- **Sections to read:** Entire file (~77 lines).
- **Why required:** Prevents accidental modification of reasoning code during UX work. Lists every invariant that must be preserved and the current architecture pipeline. Essential safety document.
- **Size:** small

### docs/current-working-principles.md (new — Experiment 32)
- **Purpose:** Default principles guidance for product, reasoning, and engineering work. Separates current principles from aspirational architecture.
- **Sections to read:** Entire file (~60 lines).
- **Why required:** Provides only the guidance that should influence work today, verified against current implementation. Reduces ambiguity about which principles are active versus aspirational.
- **Size:** small

### docs/design-evolution/README.md (selected chapters only)
- **Purpose:** Chronological record of design decisions, experiments, and their conclusions. Load the specific chapter via the archive index — do not load all chapters.
- **Sections to read:**
  - ch4: Experiments 23 through 25B (current engine experiments);
  - ch8: Experiments 47–51;
  - The Return-to-Work Note entries in each relevant chapter for recent experiment closeout.
- **Why required:** The minimum history needed to understand what was learned in the active experiment chain and where the pause decision sits. Do not read experiments before v23 unless you need historical context.
- **Size:** varies by chapter (progressive loading recommended)

### docs/project-knowledge-inventory.md (this file — Section 1 only)
- **Purpose:** Your own cross-reference for what to load next.
- **Sections to read:** Section 1 (Current Working Context) when you need to verify completeness.
- **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/current-handoff.md (new — Experiment 34)
- **Purpose:** Single return-to-work handoff carrying the latest stopping point in one short document. Classifies as the shortest current resume entry point.
- **Sections to read:** All eight sections when returning after a break; specific sections only when the resuming session has partial context.
- **Why required:** Replaces scattered current return notes with one obvious file. Does not duplicate full current-state or experiment history.
- **Size:** medium (current operational state — loads first, then project-state and methodology)

### 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).
- **Why required:** When generating or editing any user-facing copy, this is the authoritative guide. Short enough to load by default.
- **Size:** small

### docs/01_Confidence_Engine_Founding_Principles.md (optional — loaded on request)
- **Purpose:** The ten founding principles and the decision test.
- **Sections to read:** Entire file (~24 lines).
- **Why not default:** These are foundational but rarely change or need re-inspection during routine work. Load them when clarifying product philosophy or justifying a design direction.
- **Size:** small

---

## 2. Task-Specific References

Grouped by task domain. Only load the group relevant to your work.

### UI / UX experiments and layout
| Document | Purpose | Loaded When |
|---|---|---|
| `.claude/ux-guidelines.md` (97 lines) | Main user view, developer view priorities; "calm workspace" principle | Always loading the UX guidelines for any UI task |
| `docs/archive/experiments/pre-RTO/v0.7-user-workspace-ux-first-pass.md` (157 lines) | First UX pass: card layout, progress summary, developer details boundary — archived Phase 2B (2026-08-19). Preserved evidence, not current context. | When reviewing v0.7 UX layout decisions from archived historical context |
| `docs/ui-mock-reference.md` (≈62 lines) | Task-specific reference for UI mock scenarios and fixture data locations. Contains available scenarios, purposes, where fixture data lives, when to use each, and warnings against treating mock behaviour as live-engine evidence. | When working on UI mock development or testing scenarios |
| `docs/v0.7-ui-mock-mode.md` (291 lines) | Mock investigation mode for UI development without Ollama | When developing UI features that need fixture-driven testing |

### Graph and reasoning architecture
| Document | Purpose | Loaded When |
|---|---|---|
| `docs/v0.6-reasoning-architecture.md` (375 lines) | End-to-end pipeline, 17 deterministic stages, invariants, loop rules | When reviewing or modifying the core reasoning pipeline |
| `docs/confidence-engine-decomposition-and-atomic-reasoning-specification.md` (646 lines) | Working design specification for decomposition and atomic reasoning | When working on unknown decomposition or atomicity logic |
| `docs/investigation-state-assessment-contract.md` (232 lines) | Data contract between assessment layer and behaviour selection | When modifying the assessment output shape or versioning |
| `docs/investigation-turn-cycle.md` (287 lines) | Turn cycle architecture design | When reviewing how layers connect across a turn |

### Evidence, decision conditions, and passive classifiers
| Document | Purpose | Loaded When |
|---|---|---|
| `docs/archive/experiments/pre-RTO/v0.6-comparability-experiment.md` (48 lines) | Comparability hypothesis — observations must be comparable before contradiction — archived Phase 2B (2026-08-19). Preserved evidence, not current context. | When reviewing historical comparability assessment from archived context |
| `docs/archive/experiments/pre-RTO/v0.6-atomicity-experiment.md` (211 lines) | Atomic unknown decomposition experiment results — archived Phase 2B (2026-08-19). Preserved evidence, not current context. | When reviewing historical atomicity decisions from archived context |
| `docs/archive/experiments/pre-RTO/v0.6-selection-influence-experiment.md` (50 lines) | Selection influence — graph structure vs semantic keyword analysis — archived Phase 2B (2026-08-19). Preserved evidence, not current context. | When reviewing historical selection driver analysis from archived context |
| `docs/archive/experiments/pre-RTO/v0.5-question-priority-generalisation.md` (48 lines) | Question priority generalisation from v0.5 — archived Phase 2B (2026-08-19). Preserved evidence, not current context. | When reviewing historical prioritisation decisions from archived context |

### Facilitator behaviour and investigation state
| Document | Purpose | Loaded When |
|---|---|---|
| `docs/facilitator-behaviour.md` (340 lines) | 14 distinct facilitator behaviours; behavioural triggers; evaluation criteria | When working on behaviour selection or the narrative layer |
| `docs/investigation-state-assessment.md` (376 lines) | Architectural specification for state assessment | When reviewing how investigation phase/progress are classified |
| `docs/investigation-narrative.md` (232 lines) | Narrative layer design — translating graph to human-readable state | When working on the narrative adapter or UI text generation |
| `docs/behaviour-selection.md` (140 lines) | v0.1 implementation brief for behaviour selection | When implementing passive behaviour selection logic |

### Product principles and language
| Document | Purpose | Loaded When |
|---|---|---|
| `docs/02_Confidence_Engine_Product_Story.md` (31 lines) | The product story, problem, idea, how it works, commercial value | When defining new features or evaluating product fit |
| `docs/04_Rob_Thinking_Model.md` (32 lines) | Rob's thinking model — the working pattern that inspired the engine | When questioning whether a feature adds real value or just architecture |

### Knowledge management
| Document | Purpose | Loaded When |
|---|---|---|
| `docs/archive/experiments/context-routing/document-role-review.md` (140 lines) | Classification of deferred documents; practical routing test for UI mock and reasoning tasks — archived Phase 2B (2026-08-19). Preserved evidence, not current context. | When reviewing historical document classification decisions from archived context |
| `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 |
|---|---|---|
| `docs/orchestrator-contract.md` (113 lines) | API function signatures for analyseScenario / updateCase | When modifying API routes, request/response shapes, or orchestration logic |
| `docs/success-signals.md` (195 lines) | Observation criteria for what success looks like across the turn cycle | When designing new experiments or evaluating whether work achieves intended outcomes |
| `docs/failure-modes.md` (213 lines) | Failure mode catalogue — recorded observations, not solutions | When debugging unexpected engine behaviour or designing safeguards |

---

## 3. Historical and Archive Candidates

Documents or sections that are primarily historical evidence from past experiments. Marked **retain** because they document decisions that may be revisited, but **do not load by default**.

### Retain as Evidence (do not load by default)
| Document | Size | Why archived / why retain |
|---|---|---|
| `docs/archive/v0.6-ambiguity-generalisation.md` (40 lines) | small | Archived 2026-08-06. v0.6 experiment — superseded by later reasoning architecture decisions. See archive index for full provenance. |
| `docs/archive/v0.5-release-notes.md` (58 lines) | small | Archived 2026-08-06. Historical record of v0.5 state; nothing active depends on it. See archive index for full provenance. |
| `docs/archive/v0.4-handoff.md` (258 lines) | medium | Archived 2026-08-06. Historical handoff document from v0.4 transition; architecture has evolved since. Referenced in docs/orchestrator-contract.md as historical evidence — that reference was updated to the archive path. See archive index for full provenance. |
| `docs/archive/v0.4-route-status.md` (25 lines) | small | Archived 2026-08-06. Historical route tracking; current routes differ. See archive index for full provenance. |
| `docs/01_Confidence_Engine_Founding_Principles.md` (24 lines) | small | Foundational but not operational — load on request, not by default |

### Retain as Evidence (do not load by default)
| Document | Size | Why archived / why retain |
|---|---|---|
| `docs/archive/v0.7-observation-report.md` (136 lines) | medium | Archived 2026-08-06. Experimental observation snapshot — useful reference but not a current working document. See archive index for full provenance. |
| `docs/archive/deferred-ux-backlog.md` (376 lines) | large | Deferred and exploratory UX ideas retained for historical reference. Not commitments, priorities or active tasks. Split from `docs/backlog info.md` by Experiment 31. See archive index for full provenance. |

### Review Before Archive (may have future value; do not load by default now)
| Document | Size | Why review before archive |
|---|---|---|
| `docs/architectural-principles.md` (306 lines) | medium | Broader and aspirational architectural principles from experiments. Experiment 30 confirmed: 6 current, 4 aspirational targets, 3 overlap guardrails but add context. Role: task-specific reference for reasoning architecture work — not a statement of current implementation. Use `docs/current-working-principles.md` for default guidance instead. See `docs/archive/experiments/context-routing/document-role-review.md` §2 and Experiment 32 entry. |
| `docs/backlog info.md` (390 lines) | large | **Superseded by Experiment 31.** Content split into `docs/ui-mock-reference.md` (mock fixtures reference, ~62 lines) and `docs/archive/deferred-ux-backlog.md` (deferred UX planning, ~376 lines). See archive index for provenance. |
| Phase 2B experiment archives (see below) | various | Archived 2026-08-19 under Phase 2B context audit. All classified HISTORICAL_EVIDENCE + SAFE in Phase 1B. Moved to `docs/archive/experiments/` subdirectories. See docs/archive/README.md for updated index. |
| experiment-57* family (69 files) | various | Archived 2026-08-19 under Phase 2D context audit after carry-forward verification. Moved to `docs/archive/experiments/post-v0.8-investigation/`. Historical evidence from post-v0.8 investigation period. Load only when a specific post-v0.8 question requires it. |
| experiment-60b{1–8} family (8 files) | various | Archived 2026-08-19 under Phase 2D context audit after carry-forward verification. Moved to `docs/archive/experiments/decision-closure-integration/`. Historical evidence on decision-sufficiency experimental testing. Load only when a specific question requires it. |
| experiment-60b{19–48} family (29 files) | various | Archived 2026-08-19 under Phase 2D context audit after carry-forward verification. Moved to `docs/archive/experiments/decision-closure-integration/`. Historical evidence on investigation ownership, tie preservation, and proposition/formulation break-learning. Load only when a specific question requires it. |

### Do Not Move or Delete (evidence of design evolution)
These documents document the path from Phase 1 through Experiment 25B. Archiving them separately without review would lose the rationale behind later decisions.

| Document | Lines | Status |
|---|---|---|
| `docs/design-evolution-log.md` | 1,542 | The single most important chronology — never archive or delete |
| `docs/facilitator-behaviour.md` | 340 | Behavioural specification from Experiment 15 — retains active design value |
| `docs/confidence-engine-decomposition-and-atomic-reasoning-specification.md` | 646 | Working design spec — may be needed when resuming reasoning work |

---

## 4. Gaps and Duplications to Review

### Same principle appears in several documents
- The principle "The engine owns the complexity / user sees only the next step" appears in `01_Confidence_Engine_Founding_Principles.md`, `project-context.md`, `ux-guidelines.md`, and implicitly in `architecture-guardrails.md`. Consider consolidating or cross-referencing.
- The "calm workspace / minimal cognitive load" principle appears in `product-story.md`, `project-context.md`, `ux-guidelines.md`, and `docs/archive/experiments/pre-RTO/v0.7-user-workspace-ux-first-pass.md`.

### Current state is buried inside a long chronological log
- Experiment 25B (the most recent engine experiment) is at line ~1,483 of a 1,542-line document. A developer joining the project must scroll past 14+ phases to find the active state. Consider a "Current State" header near the top of `design-evolution-log.md`.

### No short entrypoint for active engine state
- There is no single document that summarises what the current reasoning engine does, what was learned in experiments 23–25B, and what remains provisional. The closest is `project-context.md`, which covers product direction but not experiment details.

### Old architectural description may no longer match implementation
- `docs/v0.6-reasoning-architecture.md` describes the v0.6 pipeline; experiments 15–25B have added behaviour selection, decision condition status, evidence direction, and scope-aware classification layers on top of it. The document does not reference these later additions.

### Facilitator Behaviour vs Architecture Principles — structural overlap
- `facilitator-behaviour.md` (14 behaviours) and `architectural-principles.md` (14 principles) both enumerate 14 items derived from the same experiments (1–14). The parallelism is interesting but may be coincidental. Verify whether they describe orthogonal concerns or overlapping ones.

---

## Minimum Context Test Result

After creating this inventory, I simulated a fresh-session context load using only:
- `.claude/project-context.md` (entire file)
- `.claude/architecture-guardrails.md` (entire file)
- `docs/design-evolution/README.md` ch4 (Experiments 23–25B), plus relevant chapter sections as needed
- `docs/03_Confidence_Engine_Language_Guide.md` (entire file)

Five questions answered from this set:

| Question | Answer | Source |
|---|---|---|
| **What is the Confidence Engine trying to help a user do?** | Help people take justified next steps when a problem feels too big to know where to start — by breaking complexity into small pieces, building a reasoning graph, asking one question at a time, and updating until confidence is sufficient or remaining uncertainty is clear. | `project-context.md` + `design-evolution-log.md` Phases 1–4 |
| **What is the current engine experiment status?** | Paused. Engine experiments concluded with Experiment 25B (scope-aware condition status). Current focus is UX presentation improvements (v0.7 user workspace), not reasoning logic changes. | `project-context.md` + `design-evolution-log.md` Exp 25B |
| **What did Experiment 25B establish?** | Scope-aware evidence-condition comparison: the engine now distinguishes direct evidence from relevant-but-different claims by checking subject, timeframe, and claim type. It confirmed that present-state evidence does not settle future-feasibility conditions (e.g., "no current EU compliance" ≠ "compliance is impossible"). All tests pass. | `design-evolution-log.md` Exp 25A–25B |
| **What remains provisional?** | The phrase-based scope detection in Exp 25A/B is narrow and replaceable — not a finished language-understanding system. The passive classifier layers (Exps 23–25B) are not yet integrated into the active reasoning path. The next question selection pipeline needs re-evaluation when experiments resume. | `design-evolution-log.md` Exp 25A "Limitations" + Exp 25B conclusion |
| **What work is intentionally paused?** | All engine experiments beyond Exp 25B. No reasoning architecture changes, no new classifiers, no active integration of passive layers. Current work is UX usability, presentation clarity, and loading feedback. | `project-context.md` ("Do not resume broad reasoning architecture work unless a repeated observed failure clearly requires it") + `design-evolution-log.md` Exp 25B Return-to-Work Note |

### Missing Context Discovered
None. The five questions were answered accurately from the minimum context set. No additional document was required.

---

## Return-to-Work Note

Engine experiments paused after Experiment 25B, which established scope-aware condition status classification — distinguishing direct evidence from relevant-but-different claims by checking subject, timeframe, and claim type. Present-state evidence does not settle future-feasibility conditions. The passive classifier layers remain isolated; no active integration yet. Knowledge-management experiments continue: five historical documents archived per Experiment 29; backlog info.md split in Experiment 31 into `docs/ui-mock-reference.md` (mock scenarios reference) and `docs/archive/deferred-ux-backlog.md` (deferred UX planning). Neither backlog item deleted or promoted. **Phase 2B context audit (2026-08-19):** ~76 historical experiment files moved to `docs/archive/experiments/` under eight subdirectories — preserved as evidence, removed from default context loading paths. No methodology or current operational paths changed. First file to inspect when resuming: `.claude/project-context.md`, then consult `docs/design-evolution/README.md` (ch4 for Experiments 23–25B).