| --- |
| language: |
| - en |
| license: apache-2.0 |
| pipeline_tag: robotics |
| tags: |
| - OpenRAL |
| - rskill |
| - any |
| inference: false |
| --- |
| |
| # rskill-playbook-clarify_ambiguity |
| |
| A `kind: playbook` rSkill: a symbolic S2 **decision procedure** the |
| Reasoner reads, not a neural policy. It carries no weights — the authored |
| [`PLAYBOOK.md`](./PLAYBOOK.md) *is* its runtime. |
| |
| ## What this skill does |
| |
| Resolves an underspecified or ambiguous goal **before** acting. When the request |
| admits more than one interpretation — two candidate bowls, a missing destination, |
| an unsafe-to-guess choice — it disambiguates from spatial memory, then from the |
| scene, and only then asks the operator a concise question; it **never** guesses on |
| an irreversible action (placing, pouring, opening). Concrete walkthrough: the |
| two-bowls example in [`PLAYBOOK.md`](./PLAYBOOK.md). |
| |
| ## How it works |
| |
| This playbook is **content, not code**. When installed, the reasoner injects |
| `PLAYBOOK.md` into its system prompt and follows the SOP, composing tools it |
| already has (`query_scene`, `memory_search`, `recall_object`, `emit_prompt`). It |
| is `role: s2` and is **never** dispatched through `ExecuteSkill`. It actuates |
| nothing: its job is to gate the downstream `execute_rskill` → Action chunk → C++ |
| safety kernel with a single unambiguous goal — the playbook holds no actuation |
| authority (CLAUDE.md §1.1). |
|
|
| ### Observation → action contract |
|
|
| None. A playbook emits no `Action` chunks and requires no actuators |
| (`actuators_required: []`, `chunk_size: 1`). Its "output" is the sequence of |
| tool calls the reasoner makes while following the SOP, bounded by |
| `playbook.max_steps`. |
|
|
| ## How it was authored / Upstream provenance |
|
|
| N/A — a playbook is **hand-authored**, not trained: it has no weights and no |
| upstream model. Its provenance is the authoring decision record |
| (also linked via `paper_url`). To change behaviour, edit `PLAYBOOK.md` and bump |
| `version`. |
|
|
| ## Supported robots |
|
|
| Embodiment-agnostic — declares the explicit wildcard `embodiment_tags: ["any"]` |
| (never an empty list) and an empty `capabilities_required: {}`: resolving an |
| ambiguous reference is operator interaction plus memory/scene queries, so it |
| works on **any** robot. The read-only scene/memory queries are gated at runtime by |
| the composed tools, not by this playbook's flags. |
|
|
| ## Sensors required |
|
|
| None directly. The tools it composes declare their own sensor needs. |
|
|
| ## Manifest summary |
|
|
| - `kind: playbook`, `role: s2`, `actions: [plan]`, `chunk_size: 1`. |
| - `playbook.trigger`: the goal is underspecified or ambiguous. |
| - `playbook.done_predicate`: the goal has a single unambiguous interpretation, |
| confirmed from memory/scene or by the operator. |
| - `playbook.max_steps`: 5. |
|
|
| ## Quick start |
|
|
| ```python |
| from openral_core.schemas import RSkillManifest |
| |
| m = RSkillManifest.from_yaml("rskills/clarify-ambiguity/rskill.yaml") |
| assert m.kind == "playbook" and m.playbook is not None |
| print(m.playbook.trigger) |
| ``` |
|
|
| ## Reproduction |
|
|
| Packaging-only: the manifest + SOP are validated by |
| `tests/unit/test_playbook_rskill_manifest.py`. There is no benchmark number to |
| reproduce; the playbook's behaviour is exercised by the reasoner integration |
| tests in later phases. |
|
|
| ## Evaluation |
|
|
| N/A — no `eval/*.json`; a playbook produces no benchmarkable policy output. |
|
|
| ## License |
|
|
| - **Code / content:** Apache-2.0. |
| - **Weights:** none. |
|
|
| ## See also |
|
|
| - [`PLAYBOOK.md`](./PLAYBOOK.md) — the decision procedure itself. |
|
|
