| # clarify-ambiguity |
|
|
| > **Hand-authored decision procedure (SOP).** Unlike the generated `SKILL.md` |
| > discovery view, this file is the *content the S2 Reasoner reads and follows*. |
| > It is injected into the reasoner's system prompt when this playbook is |
| > installed. The `rskill.yaml` `playbook.body_uri` points here. |
| |
| ## Trigger |
| The instruction has more than one valid interpretation — e.g. "put the bowl in |
| the drawer" when **two** bowls are present, or a request with a **missing** |
| destination ("put it away" with no place given). Any underspecified or |
| unsafe-to-guess referent or parameter trips this playbook **before** acting. |
| |
| ## Preconditions |
| - A spatial-memory backend is available (`memory_search` / `recall_object` tools). |
| - A scene query is available (`query_scene`) to enumerate candidate referents. |
| - An operator channel is available (`emit_prompt`) for the disambiguation question. |
|
|
| ## Steps |
| 1. **Detect.** Pin down the ambiguity precisely: *which* referent or parameter |
| is unresolved (the target object? the destination? a side/colour?), and *how |
| many* candidates fit. If exactly one interpretation is valid, there is no |
| ambiguity — exit and proceed. |
| 2. **Resolve from memory first.** Call `memory_search(<referent>)` over the |
| `MEMORY.md` Preferences log for a stated user preference that disambiguates |
| ("the user means the **left** bowl"). A recorded preference beats asking again. |
| 3. **Resolve from the scene.** Call `query_scene` / `recall_object(<referent>)`. |
| If exactly **one** candidate actually matches the description in the current |
| scene, the ambiguity is resolved — skip to **Verify**. |
| 4. **Ask, don't guess** (only if STILL ambiguous **and** the action is |
| irreversible — placing, pouring, opening). `emit_prompt` a short, **specific** |
| disambiguation question to the operator ("There are two black bowls — the |
| **left** one or the **right** one?") and **WAIT** for the answer. Do not guess. |
| 5. **Record the resolution.** Once resolved, `memory_write(op=add, |
| section="preferences", target=<referent>, content=<resolution>)` so the same |
| question isn't asked again on the next task. |
| |
| ## Verify (done predicate) |
| A **single concrete** referent / parameter, sourced from memory, the scene, or |
| the operator. The downstream skill now has an unambiguous goal to dispatch. |
| |
| ## Fallbacks |
| - No operator response within the task budget → **hold the action** and |
| `emit_prompt` that the task is blocked pending clarification. This is the |
| terminal human-handoff rung; **never** proceed on a guess for an irreversible |
| step. |
| - **Never** loop past `max_steps`. Every candidate considered, every memory/scene |
| query, and the operator exchange are on the OTel trace, so the resolution is |
| replayable. |
|
|
| ## Safety |
| This playbook only *decides* — it resolves the goal and then **gates** the |
| downstream skill. Refusing to guess on an irreversible action is the safe |
| default (CLAUDE.md §1.1, §1.4): a wrong referent would yield a wrong placement |
| the C++ safety kernel cannot un-do, so the playbook asks first rather than |
| relaxing any check. Every motion it eventually unblocks still crosses the kernel. |
|
|
