PLAYBOOK.md

stage-for-manipulation

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

A chosen manipulation rSkill declares a starting_pose (pre-grasp) that the robot has not yet reached (e.g. a pick policy expects the gripper hovering above the black bowl, but the arm is parked at home). Dispatching the manipulation from a bad initial pose is a common, avoidable grasp failure.

Preconditions

• The target manipulation skill and its starting_pose are known (read from the skill's manifest / contract).
• An arm-motion approach skill is installed — the collision-aware MoveGroup plan-arm rSkill (openral-moveit-plan-arm) — and/or a navigate skill for mobile bases.

Steps

1. Read the pre-grasp. Read the target manipulation skill's starting_pose (the declared pre-grasp the policy expects to begin from).
2. Base staging (mobile only). If the robot has a mobile base, resolve_place a stand pose that puts the target inside the arm's workspace, then execute_rskill(NAVIGATE, goal=place). Skip on a fixed-base arm.
3. Approach to pre-grasp. execute_rskill the collision-aware approach skill (the MoveGroup plan-arm rSkill) retargeted at starting_pose, so the arm moves to the pre-grasp under MoveIt. Never a hand-rolled IK.
4. Verify. query_scene to confirm the pre-grasp ("is the gripper positioned above the black bowl?"). Treat an unconfirmed pose as not staged.
5. Hand back. Only once verified, return control so the manipulation policy runs from a good initial pose.

Verify (done predicate)

The gripper (and base, for mobile embodiments) are at the declared starting_pose pre-grasp, confirmed by query_scene. An unverified pose is a failure, not a success — do not hand control to the manipulation policy.

Fallbacks

• The approach skill cannot plan a collision-free path to starting_pose (obstructed / unreachable pre-grasp) → emit_prompt that staging failed, so the reasoner replans or hands off rather than dispatching a manipulation from a bad pose. This is the terminal human-handoff rung of the replanning ladder.
• Pairs with the preflight-reach playbook (which checks reachability before a skill is even chosen); this one stages and verifies the chosen skill's pose.
• Never loop past max_steps. Every approach attempt and its outcome are on the OTel trace, so staging is replayable.

Safety

This playbook only decides and sequences. Every motion it triggers is an execute_rskill → Action chunk that still crosses the C++ safety kernel; a bad starting_pose yields a plan the kernel still vetoes, never a relaxed check (CLAUDE.md §1.1).