109 lines
11 KiB
Markdown
109 lines
11 KiB
Markdown
# 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`.
|
|
|
|
---
|
|
|
|
## 0. Axiomatic Principles (Durable Methodology)
|
|
|
|
> The following principles capture the irreducible core of the Confidence Engine methodology.
|
|
> They apply regardless of delivery platform, technology stack, or interface choice.
|
|
> New work must not contradict these axioms without explicit methodological review.
|
|
|
|
### A1 — Delivery-platform independence
|
|
|
|
The Confidence Engine is a reasoning methodology, not an LLM product, workshop format, software UI, graph implementation, book, or any other delivery mechanism. The method defines reasoning activities — surfacing questions, capturing contributions, identifying uncertainty, connecting relevant contributions, exposing what remains unresolved, helping the user understand where they are — and those activities may be delivered through a human facilitator, a book or workbook, software, an LLM-assisted application, or another future delivery mechanism. No single delivery platform owns the methodology.
|
|
|
|
### A2 — The Engine facilitates; the user directs
|
|
|
|
The Engine may expose, suggest or infer possible questions and relationships, but the user chooses what to investigate next. The Engine does NOT determine: the mandatory next question, the branch the user must enter, the decision the user should make, or when all uncertainty must be resolved. What it surfaces (possible questions, new connections, open uncertainties, branches waiting for information, changes in understanding) remains invitations or proposals. The user directs the investigation.
|
|
|
|
### A3 — Reasoning operates on meaning, not prescribed vocabulary
|
|
|
|
The Confidence Engine is domain-agnostic and language-agnostic. Its fixed vocabulary should describe generic reasoning structure (contribution, observation, uncertainty, assumption, question, relationship), not subject-matter terminology. Domain-specific dictionaries are not the basis of semantic reasoning. Language-specific keyword dictionaries are not the basis of semantic reasoning. Fixed phrase/keyword scoring must not substitute for understanding. This is consistent with learning that wording/shape sensitivity makes deterministic semantic classification brittle.
|
|
|
|
### A4 — Semantic interpretation is a suitable facilitation capability
|
|
|
|
Where meaning depends on language, semantic interpretation may be used to assist the facilitator role. A human facilitator can perform this operation. An LLM may also assist because language understanding is an appropriate capability for this task. Any inferred relationship remains a proposed interpretation until handled according to the delivery method. The LLM must not own the relationship, make the decision, determine truth, or be declared required.
|
|
|
|
### A5 — Deterministic logic preserves structure and integrity; it does not imitate semantic understanding
|
|
|
|
Use deterministic software where the problem is genuinely deterministic (identity, storage, provenance, routing, staleness checks, record integrity, known explicit links). Use semantic interpretation where the problem is genuinely about meaning. Do not rebuild semantic judgment as a domain dictionary simply because deterministic code is faster or easier to test.
|
|
|
|
### A6 — Investigation is non-linear
|
|
|
|
The Confidence Engine does not require investigation to proceed as one sequential chain. Questions create separate lines of inquiry. A branch may be active, waiting for information, paused, revisited later, or sufficiently explored for now. The user may move between branches. This reflects how investigation itself works, not merely an async-software optimisation.
|
|
|
|
### A7 — Background assistance must not redirect the user
|
|
|
|
Semantic assistance may complete asynchronously without blocking the user's current work. A delivery platform may capture the user's contribution immediately, allow them to continue elsewhere, complete semantic interpretation in the background, and surface a possible connection later. But a late result must NOT move the user to another branch, replace what they are currently doing, silently choose the next question, or interrupt ownership of the investigation. Background reasoning may create something new for the user to notice, but it must not decide where the user goes next.
|
|
|
|
### A8 — Closure is user-owned and may be provisional
|
|
|
|
Closure does not require complete resolution of every branch or uncertainty. The user may decide there is enough information for now, remaining uncertainty is not material enough to pursue, the effort to learn more is not worthwhile, the decision can be made with what is known, or the investigation should simply pause. "Resolved" means reasoning content is answered/settled. "Closed for now" means the user chooses to stop investigating at this point. The reasoning record and unresolved questions remain available for future return. A later change in circumstances or new evidence may justify reopening the investigation. Do not define a closure score or threshold.
|
|
|
|
### A9 — The reasoning structure may be graph-like without forcing a graph UI
|
|
|
|
The underlying reasoning record may be connected and non-linear, while presentation remains flexible. Possible delivery views include: focused question view, notebook/branch view, map/mind-map/tree view, timeline, summary, voice interaction, book/workbook structure. These are views over the reasoning record, not different methodologies. Mind-map, family tree, or graph visualization must never be a required interface — they are presentation possibilities only.
|
|
|
|
### A10 — Progressive disclosure mirrors progressive reasoning
|
|
|
|
The Engine breaks a large situation into manageable pieces; the interface should not then expose the entire complexity by default. The user should normally see the smallest useful part of the reasoning needed for what they are doing now, while wider structure remains available when they choose to inspect it. Progressive disclosure should reduce distraction and cognitive overload while preserving access to the wider reasoning structure.
|
|
|
|
### A11 — Multilingual flexibility follows from meaning-based reasoning
|
|
|
|
A methodology based on generic reasoning structure and semantic interpretation is more naturally portable across languages than one dependent on an English keyword dictionary. The Confidence Engine itself must not encode English/domain vocabulary as the definition of reasoning meaning. A delivery mechanism may provide semantic interpretation in the language being used. This does not claim perfect multilingual equivalence or that every LLM performs equally well in every language.
|
|
|
|
### A12 — Latency is an implementation trade-off, not a reason to distort the method
|
|
|
|
Semantic interpretation may be slower than deterministic checks, but current model latency should not redefine the reasoning methodology. Establish the smallest correct reasoning operation first; optimise delivery later.
|
|
|
|
---
|
|
|
|
## Classification discipline for future work
|
|
|
|
When considering new development:
|
|
|
|
| This belongs as | Examples |
|
|
|---|---|
|
|
| **DURABLE METHODOLOGY PRINCIPLE** | user directs investigation, delivery-platform independence, meaning over prescribed vocabulary, non-linear investigation, provisional closure, progressive disclosure |
|
|
| **IMPLEMENTATION HYPOTHESIS** | asynchronous LLM inference, hybrid deterministic/semantic fast path, notification badges, map/tree UI, background worker architecture |
|
|
| **EXPERIMENTAL EVIDENCE** | individual experiment results (e.g. one relationship discovery test) |
|
|
|
|
> Do not accidentally promote implementation ideas into methodology.
|
|
|
|
---
|
|
|
|
## Hybrid interpretation clarification (implementation hypothesis only)
|
|
|
|
A delivery platform may use a conservative deterministic fast path for genuinely structural cases and semantic interpretation when meaning is required. The guardrail: the deterministic layer must not become a hidden semantic dictionary. This architecture has NOT been selected.
|
|
|
|
## 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`.
|