---
title: Moves
description: "Ranked next actions, prioritized by what would reduce the most uncertainty."
---

Without recommended next actions, the world model is informative but not action-guiding. Moves turn understanding into direction: the engine's ranked answer to "given what the agent currently believes, what should it investigate next?" Each move targets a specific belief, gap, or contradiction and reports how much acting on it would sharpen the agent's picture.

## What a Move Is

A move is a recommended action the system surfaces based on the current belief state. Each move has an action type, a target, a reason, and an expected value representing how much it would improve the agent's understanding.

```ts
{
  action: 'gather_evidence',
  target: 'Missing APAC market analysis',
  reason: 'High-impact gap with 3 downstream dependencies',
  value: 0.72,
  executor: 'agent',
}
```

- **action.** The type of move: `clarify`, `resolve_uncertainty`, `gather_evidence`, `compare_paths`.
- **target.** The belief, gap, or contradiction the move addresses.
- **reason.** Why this move matters, in natural language.
- **value.** How much this move would reduce uncertainty, 0–1. Higher means a bigger shift in the picture.
- **executor.** Who should act: `agent`, `user`, or `both`.

## Move Types

| Action | When it surfaces |
|--------|-----------------|
| `gather_evidence` | A gap or weakly supported belief needs investigation |
| `clarify` | A contradiction exists between beliefs |
| `resolve_uncertainty` | A load-bearing belief has insufficient evidence |
| `compare_paths` | Multiple valid interpretations need a decision framework |

Each action can have a subtype for specificity:

| Subtype | Description |
|---------|-------------|
| `research` | Find external data or sources |
| `validate_assumption` | Test whether an assumption holds |
| `resolve_contradiction` | Address conflicting beliefs |
| `quantify_risk` | Measure exposure on a risk belief |
| `design_test` | Propose an experiment to confirm or refute |
| `synthesize` | Combine multiple findings into a conclusion |
| `reframe` | Restructure the problem based on new information |

## How Moves Are Ranked

Moves are ranked by how much they would reduce uncertainty in the beliefs that matter most.

A gap with many downstream dependencies generates a higher-value move than a gap with none. A contradiction between two **load-bearing** beliefs (beliefs that other beliefs derive from, so if they're wrong the rest collapse) generates a higher-value clarify move than a contradiction between peripheral claims that nothing depends on.

The system considers:
- How much uncertainty the move would reduce
- How many other beliefs depend on the target
- Whether the target belief is load-bearing (see [Clarity](/dev/core/clarity) for how the engine identifies them)
- The current clarity score and what would improve it most

## Reading Moves

Moves are returned from every major SDK method:

```ts
// Before the agent acts
const context = await beliefs.before(userMessage)
console.log(context.moves)  // ranked actions for this turn

// After the agent acts
const delta = await beliefs.after(result.text)
console.log(delta.moves)    // updated recommendations

// Full world state
const world = await beliefs.read()
console.log(world.moves)    // all current recommendations
```

## Routing on Moves

Use moves to direct agent behavior:

```ts
const delta = await beliefs.after(result.text)
const next = delta.moves[0]

if (!next) {
  // No recommended actions. Clarity is likely high.
  await finalize(delta.state)
} else if (next.action === 'gather_evidence') {
  await runResearch(next.target)
} else if (next.action === 'clarify') {
  await resolveContradiction(next.target)
} else if (next.action === 'resolve_uncertainty') {
  await deepDive(next.target)
} else if (next.action === 'compare_paths') {
  await presentTradeoffs(next.target)
}
```

## Executor

The `executor` field indicates who should act on the move.

| Executor | Meaning |
|----------|---------|
| `agent` | The agent can handle this autonomously |
| `user` | This requires human input or judgment |
| `both` | The agent can start, but the user needs to weigh in |

A `user` executor move might surface when the system detects a value judgment or strategic decision that the agent should not make alone.

<CardGroup cols={3}>
  <DocsCard title="World" description="The full state: beliefs, edges, clarity, and moves together." href="/dev/core/world" />
  <DocsCard title="Moves: SDK" description="List, generate, and act on moves with beliefs.moves.*." href="/dev/sdk/moves" />
  <DocsCard title="Patterns" description="Move-driven routing and other common patterns." href="/dev/sdk/patterns" />
</CardGroup>