confidence-engine/.claude/project-context.md

Project Context

Start with docs/current-project-state.md. Use docs/project-knowledge-inventory.md to locate task-specific or historical context. Do not read the full design-evolution log unless a named experiment is required. Do not load docs/archive/ by default; use docs/archive/README.md to locate historical evidence when specifically required.

What the Confidence Engine is

The Confidence Engine is a structured reasoning tool intended to help people decide whether they have enough justified confidence to act.

It does not simply answer the user's original question.

It:

1. reconstructs the situation;
2. separates observations, assumptions, relationships and unknowns;
3. creates a structured reasoning graph;
4. selects the most useful unresolved uncertainty;
5. asks one simple question;
6. updates the graph from the answer;
7. repeats until action is justified or the remaining uncertainty is clear.

A chatbot remembers the conversation.

The Confidence Engine preserves the state of the reasoning.

Product direction

The eventual product should feel like a calm, capable investigator helping the user think one step at a time.

The user should not need to understand:

• graph theory;
• node IDs;
• internal enums;
• schemas;
• prompt versions;
• proposal validation;
• model-provider details.

Those remain available through developer/debug views.

Core product promise

The engine should help a user reach one of these states:

• I have enough justified confidence to act.
• I do not yet have enough confidence, but I know what to investigate next.
• I have discovered that my original question needs reframing.

Current development stage

The deterministic reasoning architecture reached a stable alpha checkpoint.

Current work is primarily improving:

• usability;
• presentation;
• loading feedback;
• plain-language explanations;
• separation of user and developer views.

Do not resume broad reasoning architecture work unless a repeated observed failure clearly requires it.

Important philosophy

Complicated situations are made from smaller parts.

Each part may influence the whole, but parts do not necessarily carry equal weight.

Previous cases may suggest where to investigate, but they must never determine the outcome of a new case.

Every case begins with no accepted evidence from previous cases.

Product Principle: TL;DR First

The Confidence Workspace is not a document viewer or chat transcript. It is an active investigation workspace.

At any point, the interface should allow a user returning after seconds, minutes or hours to understand where they are within a few seconds.

The workspace should always answer:

1. What is the situation?
2. What have we established?
3. What is the single most important thing to determine next?
4. Why does that matter?
5. How close are we to having sufficient confidence?

The interface should minimise cognitive load by presenting the current state first and allowing progressively deeper exploration only when requested.

The engine may contain hundreds of reasoning nodes; the user should only see the information required to take the next meaningful action.

Why workspace layout matters (v0.7)

This phase optimises for simultaneous visibility instead of sequential scrolling. Related panels — Understanding alongside Investigation Map, Situation alongside History — can appear side-by-side on wide screens while mobile continues to stack everything vertically. The reasoning engine is completely unaware of these changes; only the presentation layer is affected.

Routing Notes

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: docs/current-project-state.md, then docs/project-knowledge-inventory.md.