# Usage Guide

## 1. Open the Lab

Open the canonical page at:

https://deshimarusakaguchi.com/llm-ambiguity-lab/

The public v1 interface requires no account and no LLM API configuration.

## 2. Start with the preset cases

The six preset buttons are the best way to understand the control model because they are deterministic reference scenarios.

### Preset 1: Clearly grounded

**Input**

```text
Summarize the DCRL explanation above as JSON.
```

Expected state: `READY`

Why: the task, target object, contextual reference, and output format are all explicitly represented in the reference scenario.

### Preset 2: Minor condition missing

**Input**

```text
Summarize the DCRL explanation above.
```

Expected state: `READY_WITH_DISCLOSED_ASSUMPTION`

Why: the task and target are resolved, while the output format is treated as a non-critical missing condition. The simulator discloses a concise-prose default and proceeds.

### Preset 3: Referential ambiguity

**Input**

```text
Summarize it.
```

Expected state: `CLARIFICATION_REQUIRED`

Why: `summarize` identifies the operation, but `it` does not identify the target object.

### Preset 4: Task ambiguity

**Input**

```text
Improve the previous section.
```

Expected state: `CLARIFICATION_REQUIRED`

Why: the target is grounded, but `improve` does not specify which revision goal matters. The Lab offers bounded alternatives such as clarity, length, or technical detail.

### Preset 5: Mixed ambiguity

**Input**

```text
Do that and make it better.
```

Expected state: `CLARIFICATION_REQUIRED`

Why: both the referent and the meaning of `better` are unresolved.

### Preset 6: Severe context loss

**Input**

```text
Thanks. Please proceed.
```

Expected state: `PENDING_SPECIFICATION`

Why: the simulator cannot identify the target task or the object to which the request refers.

## 3. Try free-text input

Enter your own instruction and select **Analyze Instruction**.

The free-text mode uses a limited deterministic heuristic. It can identify several task verbs, basic target phrases, simple output-format words, referential signals, continuation language, and vague revision language.

It is deliberately not an LLM-backed semantic parser.

## 4. Read the output in this order

### 4.1 Resolution State

Start with the control decision:

- `READY`
- `READY_WITH_DISCLOSED_ASSUMPTION`
- `CLARIFICATION_REQUIRED`
- `PENDING_SPECIFICATION`

### 4.2 Target Task and Target Object

Ask two separate questions:

1. What operation does the instruction request?
2. What does that operation apply to?

This distinction is central to the Lab. `Summarize it` contains a recognizable operation but an unresolved object.

### 4.3 Context Grounding

- `grounded`: the simulator can connect the instruction to an identifiable target representation.
- `partial`: some contextual signal exists, but an essential reference is unresolved.
- `ungrounded`: the simulator has no usable target context.

### 4.4 Ambiguity Type

The Lab reports one of:

- `none`
- `lexical`
- `referential`
- `intent_task`
- `mixed`

The v1 free-text heuristic is strongest as a demonstration of referential and task ambiguity. It is not a general lexical-disambiguation engine.

### 4.5 Missing Parameters

This list explains what prevents a stronger resolution state.

Common examples:

- `target_task`
- `target_object`
- `referent`
- `output_format`
- `revision_goal`

### 4.6 Plausible Interpretations

When materially different interpretations are easy to represent, the Lab shows a small candidate set. These are teaching aids, not exhaustive hypotheses.

### 4.7 Assumption Disclosure

This appears when the state is `READY_WITH_DISCLOSED_ASSUMPTION`.

The principle is:

> If a missing condition is non-critical and a safe default exists, disclose the default rather than silently inventing it.

### 4.8 Recommended System Action

This is the final control decision generated by the simulation.

## 5. Use the Context Resolution Policy slider

The slider isolates the policy layer from language analysis.

Move it across the four illustrative bands:

| Score | State | Behavior |
|---|---|---|
| `0.90–1.00` | `READY` | Proceed directly. |
| `0.70–0.89` | `READY_WITH_DISCLOSED_ASSUMPTION` | Disclose a safe default and proceed. |
| `0.40–0.69` | `CLARIFICATION_REQUIRED` | Pause and clarify. |
| `0.00–0.39` | `PENDING_SPECIFICATION` | Stop and request task specification. |

The slider does not claim that these thresholds are optimal for every agent.

## 6. Use the DCRL section as a design checklist

For an ambiguous instruction, ask:

1. **Detect**: What is known? What is missing?
2. **Clarify**: Which missing item would materially change the action?
3. **Resolve**: Is the task sufficiently specified to choose an execution path?
4. **Learn**: If the system has an appropriate memory mechanism, is there a reusable correction or preference worth preserving?

## 7. Example design exercise

Consider:

```text
Rewrite it in Markdown.
```

A useful control analysis separates:

- task: `revise`
- output format: `markdown`
- target object: unresolved because `it` has no usable referent in isolation

The correct architectural question is not merely whether the sentence is understandable English. It is whether the agent has enough information to act on the correct object.

## 8. What not to infer from the output

Do not read `0.82` as “82% likely to be correct.”

Do not interpret a green state as a safety guarantee.

Do not interpret a clarification state as evidence that a real LLM would necessarily fail on the same sentence.

The Lab demonstrates an inspectable policy, not a universal model evaluator.

For details, see [methodology.md](methodology.md) and [limitations.md](limitations.md).