experiment: separate current principles from architectural aspirations

2026-08-06 15:07:06 +01:00
parent a4bbe0ef3f
commit 51f0c11bc8
5 changed files with 108 additions and 1 deletions
@@ -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:
@@ -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.
@@ -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`.
@@ -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.
+
+---
@@ -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)