Clarity

The Job

The world model exists to answer one recurring question: investigate more, or move? Every agent loop hits that fork. Lean too far one way and the agent acts on a hunch. Lean the other way and it researches a question it already answered.

Clarity is the single 0-1 number that settles the fork, read straight off the belief state. Low clarity means keep investigating. High clarity means there is enough on the table to act, even when the call itself is hard. Clarity is that judgment compressed into one number your loop can branch on.

The Two-Channel Insight

Take two claims, both sitting at 50%. One was typed once and never tested, a coin flip nobody touched again. The other has forty observations behind it that genuinely split down the middle.

Same number, opposite situations. The first needs research. The second needs a decision. A scalar confidence cannot tell them apart, so the belief state tracks two channels:

1┌────────────────────────────────────────────────────────────────┐
2│  THE TWO QUESTIONS                                             │
3│                                                                │
4│  1. DECISION RESOLUTION  ("Can we make a call?")               │
5│       80%   yes, lean toward it                                │
6│       50%   no, it is ambiguous                                │
7│       99%   strong signal                                      │
8│                                                                │
9│  2. KNOWLEDGE CERTAINTY  ("Have we done the work?")            │
10│       just stated   no evidence yet                            │
11│       10 obs        some certainty                             │
12│       100 obs       high certainty in the assessment           │
13│                                                                │
14└────────────────────────────────────────────────────────────────┘

Decision resolution is where the posterior sits, how far the balance of evidence has moved off ambiguous. Knowledge certainty is how much evidence stands behind that position. The two move independently, and that independence is the whole point.

The Four Quadrants

1                       Knowledge Certainty
2                      Low               High
3                ┌─────────────────┬─────────────────┐
4   High         │  Belief without │  Validated      │
5   Decision     │  evidence.      │  belief.        │
6   Resolution   │  > Investigate. │  Ready to act.  │
7                ├─────────────────┼─────────────────┤
8   Low          │  No idea.       │  Genuinely      │
9   Decision     │  Start from     │  uncertain.     │
10   Resolution   │  scratch.       │  > Decide,      │
11                │                 │    do not       │
12                │                 │    research.    │
13                └─────────────────┴─────────────────┘

The bottom-right quadrant is the one most systems miss. "We did the work, and it is a genuinely close call" is a conclusion, not a failure. The right response is to help the user decide, not to send the agent back to research a question already settled as uncertain.

What Clarity Folds In

Clarity is a scalar aggregate. The two primary channels carry it: decision resolution and knowledge certainty are what the score is built to summarize. Two further reads on the state then apply as penalties, docking clarity when the picture is incoherent or thin in places that matter.

Decision resolution (primary channel). Are the key claims far enough from ambiguous to act on?

Knowledge certainty (primary channel). Has enough evidence accumulated to trust the current picture?

Coherence (penalty). Unresolved contradictions pull the score down. A state that disagrees with itself is not ready to act on, however confident its individual claims look.

Coverage (penalty). Open gaps pull the score down, and a gap with more downstream dependencies pulls harder. The result is a gradient that points the agent at the gaps worth closing first.

So a high clarity score means the same thing every time: the calls that matter have resolved, the evidence behind them is real, nothing is openly contradicting, and the ground that bears on the decision is covered.

Load-Bearing Beliefs

Some beliefs hold up everything above them. A load-bearing belief is one that, if it turned out false, would take the whole plan's thinking down with it.

"The TAM is $4.2B" is load-bearing when the pricing model, the projections, and the go-to-market plan all rest on it. thinkⁿ finds these by walking the belief graph: a claim is load-bearing when many other beliefs derive from, support, or depend on it, so removing it invalidates everything downstream.

This is where clarity surfaces risk. The engine flags a load-bearing belief when its evidence is weak, has decayed past its half-life, or is contradicted, so the agent stops building on a foundation that is eroding underneath it. Those are the liveness flags that ride on the current state: stale, stable, contradicted, uncertain, computed at read time for the beliefs that matter most.

Routing on Clarity

Clarity rides back on every read. Pull it off the world model and branch your loop on it:

1const { clarity, gaps, beliefs } = await beliefs.read()
2
3if (clarity < 0.3) {
4  // Not enough to work with. Research the biggest gaps.
5  await runResearch(gaps)
6} else if (clarity > 0.7) {
7  // Enough to act. Draft recommendations.
8  await draftRecommendations(beliefs)
9} else {
10  // In between. Close the gaps that still matter.
11  await investigateGaps(gaps)
12}

It comes back on before(query) too, alongside the prompt, beliefs, goals, gaps, and the top-ranked move, so a turn can read its own readiness before it spends a token. The thresholds are yours to set. Clarity gives you a stable axis to set them on.

High Clarity Is Not High Confidence

People conflate the two, and pulling them apart is deliberate. An agent can investigate a market thoroughly, conclude it could break either way, and still land at high clarity, because it has done the work to know the question is genuinely open.

Clarity measures readiness to act, not certainty in the answer. Low clarity says "keep investigating." High clarity says "you have enough to decide," and that includes deciding the call is a hard one. The agent in the bottom-right quadrant is at high clarity and low confidence at the same time, and routing it back to research would be the wrong move.

How Knowledge Certainty Earns Itself

When you seed a belief with add(), knowledge certainty starts near zero. That is on purpose.

add('Market is $4.2B', { confidence: 0.8 }) sets the belief's starting position, so decision resolution reflects the 0.8. But the 0.8 is a weak prior, not a verdict. The engine has seen no evidence yet. Knowledge certainty tracks earned evidence: how much has actually accumulated against the claim since it was stated. It grows when the same claim picks up supporting or refuting evidence, when repeated observations reinforce it, and when tool results confirm it independently.

This is why a high-confidence add() with nothing behind it lands squarely in the "belief without evidence" quadrant, where clarity flags it for validation instead of treating your number as proof. To build knowledge certainty fast, route real agent output through after() rather than seeding everything by hand. The extraction pipeline mines evidence from the work the agent is already doing and folds it into the matching beliefs.

Where Clarity Sits