added claude context files
This commit is contained in:
@@ -0,0 +1,77 @@
|
||||
# Architecture Guardrails
|
||||
|
||||
## Hard boundary for UX tasks
|
||||
|
||||
When a task is described as UI, UX, layout, styling, loading feedback or
|
||||
presentation work, do not modify:
|
||||
|
||||
- reasoning algorithms;
|
||||
- unknown selection;
|
||||
- reasoning-pattern selection;
|
||||
- question formulation;
|
||||
- atomicity or answerability assessment;
|
||||
- graph mutation;
|
||||
- graph schemas;
|
||||
- API request or response contracts;
|
||||
- reconstruction prompts;
|
||||
- provider configuration;
|
||||
- confidence propagation;
|
||||
- compatibility validation.
|
||||
|
||||
If a UX request appears to require one of those changes, stop and report the
|
||||
dependency rather than changing it silently.
|
||||
|
||||
## Reasoning invariants
|
||||
|
||||
Preserve these invariants:
|
||||
|
||||
- The LLM proposes information; deterministic code owns graph mutation.
|
||||
- Every user-facing question comes from an explicit unresolved graph node.
|
||||
- Questions contain one primary concept and seek one coherent answer.
|
||||
- Unknowns must be atomic or decomposed.
|
||||
- Atomic wording alone is insufficient; a selected unknown must be independently
|
||||
answerable.
|
||||
- Question family must match the active reasoning pattern.
|
||||
- Active investigation nodes must be compatible with the reasoning pattern.
|
||||
- Relationship classification cannot outrun comparability assessment.
|
||||
- Ambiguity remains explicit rather than being resolved alphabetically.
|
||||
- Parent unknowns do not resolve before their completion rule is satisfied.
|
||||
- Confidence must not outrun evidence or completeness.
|
||||
- Duplicate evidence must not increase confidence.
|
||||
- Conflicting evidence caps conclusion confidence.
|
||||
- A successful update must rerun deterministic next-question selection when
|
||||
eligible unknowns remain.
|
||||
- No question is preferable to an unjustified question.
|
||||
|
||||
## Current architecture, simplified
|
||||
|
||||
Scenario
|
||||
→ reconstruction
|
||||
→ situation graph
|
||||
→ unknown selection
|
||||
→ atomicity
|
||||
→ answerability
|
||||
→ reasoning pattern
|
||||
→ investigation strategy
|
||||
→ question family
|
||||
→ question formulation
|
||||
→ complexity validation
|
||||
→ user answer
|
||||
→ proposed graph update
|
||||
→ deterministic validation/application
|
||||
→ propagation
|
||||
→ confidence/completeness update
|
||||
→ next unknown
|
||||
|
||||
## Compatibility discipline
|
||||
|
||||
Do not expand schemas merely because a model emits a synonym.
|
||||
|
||||
Prefer:
|
||||
|
||||
1. identify the source;
|
||||
2. determine whether it is a synonym;
|
||||
3. normalise deterministically when justified;
|
||||
4. retain strict validation.
|
||||
|
||||
Do not weaken validation globally to fix a single malformed response.
|
||||
@@ -0,0 +1,74 @@
|
||||
# Project Context
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,137 @@
|
||||
# UX Guidelines
|
||||
|
||||
## Main principle
|
||||
|
||||
The user should see the next useful step clearly.
|
||||
|
||||
The system may retain considerable complexity underneath, but the primary
|
||||
workspace should remain calm and understandable.
|
||||
|
||||
## Main user view
|
||||
|
||||
Prioritise:
|
||||
|
||||
1. Your situation
|
||||
2. Current understanding
|
||||
3. What we are working out
|
||||
4. Why it matters
|
||||
5. Next question
|
||||
6. Answer field
|
||||
7. Reasoning progress
|
||||
|
||||
## Developer view
|
||||
|
||||
Keep technical details behind a collapsed `Developer details` disclosure.
|
||||
|
||||
This may contain:
|
||||
|
||||
- complete situation graph;
|
||||
- graph counts;
|
||||
- nodes and edges;
|
||||
- affected and resolved nodes;
|
||||
- diagnostics;
|
||||
- proposal details;
|
||||
- raw JSON;
|
||||
- prompt and model details;
|
||||
- technical confidence data.
|
||||
|
||||
Do not remove the developer view. It remains important while the product is
|
||||
being tested.
|
||||
|
||||
## Language
|
||||
|
||||
Use plain language.
|
||||
|
||||
Prefer:
|
||||
|
||||
- `areas that still need investigation`
|
||||
- `what we are working out`
|
||||
- `why this matters`
|
||||
- `what we understand so far`
|
||||
- `next question`
|
||||
|
||||
Avoid in the main view:
|
||||
|
||||
- unknown nodes;
|
||||
- unresolved candidates;
|
||||
- activeUnknownNodeId;
|
||||
- graph references;
|
||||
- proposal compatibility;
|
||||
- candidate count;
|
||||
- internal enum values;
|
||||
- raw IDs.
|
||||
|
||||
Never display an unexplained count such as:
|
||||
|
||||
`3 remaining`
|
||||
|
||||
Explain what the count represents, or omit it.
|
||||
|
||||
Do not imply that one unresolved graph node always equals one remaining user
|
||||
question.
|
||||
|
||||
## Loading experience
|
||||
|
||||
Analysis and update requests can take around a minute with the current local
|
||||
model.
|
||||
|
||||
A disabled button is not sufficient feedback.
|
||||
|
||||
Show a visible processing card immediately.
|
||||
|
||||
Recommended initial-analysis messages:
|
||||
|
||||
- 0–10 seconds: `Reading your situation`
|
||||
- 10–25 seconds: `Building a structured understanding`
|
||||
- 25–45 seconds: `Identifying what is known and still unclear`
|
||||
- 45+ seconds: `Selecting the next useful question`
|
||||
|
||||
Recommended update messages:
|
||||
|
||||
- 0–10 seconds: `Considering your answer`
|
||||
- 10–25 seconds: `Updating the situation`
|
||||
- 25–45 seconds: `Checking what changed`
|
||||
- 45+ seconds: `Choosing the next question`
|
||||
|
||||
These messages are time-based reassurance only.
|
||||
|
||||
Do not claim that a backend stage has completed unless the backend explicitly
|
||||
reports it.
|
||||
|
||||
Show elapsed time.
|
||||
|
||||
Do not show fake progress percentages.
|
||||
|
||||
Disable duplicate submission while a request is active.
|
||||
|
||||
## Visual character
|
||||
|
||||
Aim for:
|
||||
|
||||
- calm;
|
||||
- professional;
|
||||
- spacious;
|
||||
- accessible;
|
||||
- suitable for business, consultancy and government users.
|
||||
|
||||
Prefer:
|
||||
|
||||
- clear hierarchy;
|
||||
- restrained colour;
|
||||
- generous whitespace;
|
||||
- readable line lengths;
|
||||
- consistent cards;
|
||||
- accessible contrast;
|
||||
- responsive layouts.
|
||||
|
||||
Avoid:
|
||||
|
||||
- visual clutter;
|
||||
- excessive badges;
|
||||
- neon colour;
|
||||
- unnecessary gradients;
|
||||
- glassmorphism;
|
||||
- distracting animation;
|
||||
- dashboard-style density.
|
||||
|
||||
The next question should be the strongest visual element.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Claude Code Working Rules
|
||||
|
||||
## Mandatory command constraints
|
||||
|
||||
These rules exist because previous long shell commands and streamed responses
|
||||
caused tool failures.
|
||||
|
||||
- Do not use heredocs.
|
||||
- Do not use long `node -e` commands.
|
||||
- Do not use long `python -c` commands.
|
||||
- If helper code is needed, create a small script file and run it.
|
||||
- Keep shell commands short and readable.
|
||||
- Break complex work into several commands.
|
||||
- Write large outputs to files instead of printing them.
|
||||
- Do not print full JSON responses or graph objects.
|
||||
- Do not paste complete large files into chat.
|
||||
- Prefer: tool → file → concise summary.
|
||||
- Keep final reports concise.
|
||||
- Do not narrate every implementation step.
|
||||
|
||||
## Change discipline
|
||||
|
||||
Before editing:
|
||||
|
||||
1. state the current branch;
|
||||
2. inspect `git status`;
|
||||
3. identify the relevant files;
|
||||
4. explain the smallest intended change.
|
||||
|
||||
Work on one component or concern at a time.
|
||||
|
||||
Do not combine unrelated cleanup with the requested task.
|
||||
|
||||
Do not reformat unrelated files.
|
||||
|
||||
Do not modify production reasoning code during UX tasks.
|
||||
|
||||
## Testing discipline
|
||||
|
||||
Use focused tests.
|
||||
|
||||
Do not run the full test suite unless requested or genuinely necessary.
|
||||
|
||||
Do not call Ollama in unit tests.
|
||||
|
||||
Do not run live multi-scenario evaluations for ordinary UI changes.
|
||||
|
||||
Do not run Playwright unless the task specifically requires it.
|
||||
|
||||
Do not weaken existing reasoning tests to make UI changes pass.
|
||||
|
||||
## Git discipline
|
||||
|
||||
Before committing:
|
||||
|
||||
- inspect the diff;
|
||||
- confirm no secrets;
|
||||
- confirm no internal IP addresses;
|
||||
- confirm no raw provider responses;
|
||||
- confirm no screenshots;
|
||||
- confirm no temporary scripts;
|
||||
- confirm no generated test outputs;
|
||||
- confirm only intended files changed.
|
||||
|
||||
Use a focused commit message.
|
||||
|
||||
Do not merge or tag unless explicitly requested.
|
||||
|
||||
## Response discipline
|
||||
|
||||
At the end of a task, normally report only:
|
||||
|
||||
- branch;
|
||||
- commit hash, when committed;
|
||||
- files changed;
|
||||
- behaviour changed;
|
||||
- tests;
|
||||
- lint/build;
|
||||
- manual result, if performed;
|
||||
- remaining limitation;
|
||||
- git status.
|
||||
|
||||
Stop after reporting. Do not begin the next task automatically.
|
||||
@@ -0,0 +1,44 @@
|
||||
# Confidence Engine
|
||||
|
||||
Read these project instructions before making changes:
|
||||
|
||||
- @.claude/project-context.md
|
||||
- @.claude/architecture-guardrails.md
|
||||
- @.claude/ux-guidelines.md
|
||||
- @.claude/working-rules.md
|
||||
|
||||
## Current working principle
|
||||
|
||||
The Confidence Engine helps a person move from uncertainty towards justified
|
||||
confidence by asking one simple, useful question at a time.
|
||||
|
||||
The graph preserves the state of the reasoning. The conversation is the primary
|
||||
user experience.
|
||||
|
||||
## Before changing anything
|
||||
|
||||
1. Inspect the current branch and working tree.
|
||||
2. Read the relevant implementation and tests.
|
||||
3. Identify whether the request concerns:
|
||||
- reasoning behaviour;
|
||||
- API/data contracts;
|
||||
- or presentation only.
|
||||
4. Respect the boundaries in the imported instructions.
|
||||
5. Make the smallest change that satisfies the task.
|
||||
|
||||
Do not assume an architectural redesign is wanted.
|
||||
|
||||
## Standard validation
|
||||
|
||||
For UI-only work, normally run:
|
||||
|
||||
```bash
|
||||
npm test -- --run tests/ui/scenario-form.test.jsx
|
||||
npm run lint
|
||||
npm run build
|
||||
```
|
||||
|
||||
Run additional focused tests only when relevant files are affected.
|
||||
|
||||
Do not run Ollama, Playwright, the full test suite, or evaluator suites unless the
|
||||
task explicitly requires them.
|
||||
Reference in New Issue
Block a user