chore: publish rSkill OpenRAL/rskill-playbook-clarify_ambiguity v0.1.0

PLAYBOOK.md

@@ -0,0 +1,56 @@
+# 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.

SKILL.md

@@ -0,0 +1,64 @@
+---
+name: clarify-ambiguity
+description: >-
+  S2 decision-procedure playbook (weightless). Capabilities: plan on ambiguous reference. S2 decision procedure: when the goal is underspecified or ambiguous, resolve it from memory/scene or ask the operator a concise question before acting — never guessing on an irreversible action. Composes query_scene, memory_search, recall_object and emit_prompt. Discovery view of an OpenRAL rSkill — NOT directly runnable by an agent harness; it runs via rSkill.from_pretrained + the robot HAL.
+metadata:
+  openral_rskill: true            # generated discovery view of an rSkill
+  schema_version: 0.1
+  rskill_id: OpenRAL/rskill-playbook-clarify_ambiguity
+  manifest: ./rskill.yaml
+  role: s2
+  kind: playbook
+  embodiment_tags: [any]
+  actions: [plan]
+  objects: [ambiguous reference]
+  scenes: [indoor, household]
+  chunk_size: 1
+  latency_budget: {per_chunk_ms: 5000.0}
+  license_code: Apache-2.0
+  license_weights: apache-2.0
+  paper_url: https://github.com/OpenRAL/openral/blob/master/docs/decisions.md
+---
+
+# clarify-ambiguity — rSkill discovery view
+
+> **Generated view, not a hand-written skill.** This `SKILL.md` is a discovery-only
+> mirror of [`rskill.yaml`](./rskill.yaml), produced by `tools/generate_rskill_skillmd.py`.
+> It lets tools that read the standard agent-skill format find and reason about this
+> OpenRAL rSkill. The `rskill.yaml` manifest is the single source of truth
+> (CLAUDE.md §1.3). Do not edit by hand — edit the manifest and regenerate.
+
+## What it is
+
+An OpenRAL **decision-procedure playbook (weightless)** (`role: s2`, `kind: playbook`). S2 decision procedure: when the goal is underspecified or ambiguous, resolve it from memory/scene or ask the operator a concise question before acting — never guessing on an irreversible action. Composes query_scene, memory_search, recall_object and emit_prompt.
+
+## Capabilities
+
+- **Verbs:** plan
+- **Objects:** ambiguous reference
+- **Scenes:** indoor · household
+- **Embodiments:** any
+
+## Why this is discovery-only
+
+An agent skill is natural-language instructions loaded into an LLM's context. An rSkill
+is an executable artifact: it carries a typed capability/embodiment contract
+a runtime, and a license/provenance gate — none of which fit in freeform markdown. So an
+agent can use this view to *select* the right skill, but cannot *execute* it by loading
+this file. Execution always goes through the OpenRAL loader and the robot HAL.
+
+## License
+
+- **Code:** Apache-2.0. This is a weightless rSkill (the manifest *is* the artifact).
+
+## How to actually run it (not via an agent harness)
+
+```python
+from openral_rskill import rSkill
+
+skill = rSkill.from_pretrained("OpenRAL/rskill-playbook-clarify_ambiguity")
+# the loader validates embodiment / sensors / runtime / quantization against the target
+# RobotDescription and enforces the weight-license gate before any weights load.
+```
+
+See [`rskill.yaml`](./rskill.yaml) for the authoritative, validated manifest.

rskill.yaml

@@ -0,0 +1,71 @@
+# rSkill manifest — clarify-ambiguity (kind: playbook)
+#
+# A symbolic S2 *decision procedure* the Reasoner reads (not a neural policy):
+# when the goal is underspecified or ambiguous, resolve it from memory/scene or
+# ask the operator a concise question before acting. Composes existing read-only
+# reasoner tools; carries no weights and never actuates directly (it gates the
+# downstream ExecuteRskill → Action chunk → C++ safety kernel).
+
+schema_version: "0.1"
+name: "OpenRAL/rskill-playbook-clarify_ambiguity"
+version: "0.1.0"
+license: "apache-2.0"
+role: "s2"
+kind: "playbook"
+
+# Embodiment-agnostic — a playbook is gated by capabilities_required, not by a
+# specific embodiment. Declared explicitly with the "any" wildcard (never an
+# empty list, which the manifest validator rejects).
+embodiment_tags: ["any"]
+
+# No capability flags: resolving an ambiguous reference is operator interaction
+# plus memory/scene queries — it works on any robot. The kept-empty mapping
+# `capabilities_required: {}` is the explicit "no flags" form; the read-only
+# scene/memory queries the SOP performs are gated at runtime by the composed
+# tools' own requirements, not by this playbook.
+capabilities_required: {}
+
+# A playbook actuates nothing itself.
+actuators_required: []
+
+# Required field; pinned to 1 like the perception kinds (no Action rows).
+chunk_size: 1
+
+# S2 planning budget (~0.2 Hz tick). CI enforces on the reference host.
+latency_budget:
+  per_chunk_ms: 5000.0
+
+description: >
+  S2 decision procedure: when the goal is underspecified or ambiguous, resolve
+  it from memory/scene or ask the operator a concise question before acting —
+  never guessing on an irreversible action. Composes query_scene, memory_search,
+  recall_object and emit_prompt.
+
+# RSkillAction.PLAN — registry/discovery metadata only (a playbook is role s2,
+# never an ExecuteSkill dispatch verb).
+actions:
+  - "plan"
+
+objects:
+  - "ambiguous reference"
+scenes:
+  - "indoor"
+  - "household"
+
+# Provenance citation (a playbook has no weights / upstream model repo, so a
+# citation is still required for publish-readiness — CLAUDE.md §6.4). The
+# The authoring decision record is private (OpenRAL/management); this points at
+# the public stub that explains where it lives.
+paper_url: "https://github.com/OpenRAL/openral/blob/master/docs/decisions.md"
+
+# The playbook decision-procedure contract.
+playbook:
+  trigger: "the goal is underspecified or ambiguous — multiple candidate referents, a missing target or destination, or an unsafe-to-guess choice"
+  body_uri: "./PLAYBOOK.md"
+  composes_tools:
+    - "query_scene"
+    - "memory_search"
+    - "recall_object"
+    - "emit_prompt"
+  done_predicate: "the goal has a single unambiguous interpretation, confirmed from memory/scene or by the operator"
+  max_steps: 5