PLAYBOOK.md

preflight-reach

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

About to grasp or place an object (e.g. "pick up the mug", "put the can on the shelf") but it is unclear the embodiment can physically reach the target from where it currently stands — its reachability from the current base and arm pose is uncertain.

Preconditions

• The reasoner's ## ROBOT self-model block is available (DOF, end-effectors, approximate reach, locomotion, payload limit).
• A spatial-memory / detector backend gives the target pose (recall_object / query_scene / locate_in_view tools).

Steps

1. Read the self-model (## ROBOT). Note locomotion (a fixed arm vs a mobile base), the arm's approximate reach, and the payload limit. These three facts decide everything that follows.
2. Locate the target. Call recall_object(target) (or query_scene / locate_in_view) → the target's pose. No pose → defer to the find-object playbook before continuing.
3. Reach check. Is the target within the arm's workspace from the current base pose, and within the payload limit? Compare the target pose against the self-model's reach envelope and the payload against its limit.
4. Reachable → done. If the target is in the workspace and under the payload limit, allow the manipulation skill to dispatch.
5. Out of reach AND a mobile base exists → resolve_place an approach stand pose near the target, execute_rskill(NAVIGATE, goal=stand_pose), then re-check (back to step 3) from the new base pose.
6. Fixed arm and out of reach (or over payload) → do not dispatch the manipulation skill. Hand off (see Fallbacks). A fixed arm cannot stage itself closer, so navigating is not an option.

Verify (done predicate)

The target is inside the reachable workspace — directly, or after staging the mobile base — and within the payload limit. Only then is the downstream manipulation skill allowed to dispatch.

Fallbacks

• Fixed-arm out-of-reach, or target over the payload limit → emit_prompt to the operator ("the mug is outside my workspace / too heavy; please move it closer or reduce the load"). This is the terminal human-handoff rung of the replanning ladder.
• Pairs with the stage-for-manipulation playbook: when a mobile base exists, that playbook owns the staging motion; this one owns the reach decision.
• Never loop past max_steps. Every reach check, stage, and re-check is on the OTel trace, so the decision 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 wrong reach estimate yields a bad plan the kernel still vetoes, never a relaxed check (CLAUDE.md §1.1).