PLAYBOOK.md

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.