confidence-engine/docs/current-working-principles.md

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.