home / skills / bdambrosio / cognitive_workbench / nav-backtrack

nav-backtrack skill

safe

/src/world-tools/minecraft/nav-backtrack

This skill recovers to a recent safe navigation state by exploring nav history and executing atomic moves to a validated target.

npx playbooks add skill bdambrosio/cognitive_workbench --skill nav-backtrack

Review the files below or copy the command above to add this skill to your agents.

Files (2)

Skill.md

1.1 KB

---
name: nav-backtrack
type: python
description: "Attempt to return to a recently known safe navigation state using bounded local motion."
---

# nav-backtrack

Recovery tool that searches `world_state("nav")` history for a safe prior cell and attempts to reach it using atomic nav primitives.

## Input

- `max_targets`: Integer maximum number of safe targets to try (default: `3`)

## Output

Success (`status: "success"`):
- `value`: Summary text
- `extra.recovered_to`: `{x, y, z, yaw}` position recovered to
- `extra.method`: `"step"` | `"climb"` | `"descend"`
- `extra.yaw`: Final yaw

Failure (`status: "failed"`):
- `reason`: One of `"NO_HISTORY"`, `"STATUS_FAILED"`, `"NO_SAFE_TARGET"`, `"UNREACHABLE"`

## Behavior

- Reads `world_state("nav")` and chooses up to `max_targets` safe entries
- Uses `nav-turn` + one of: `nav-move`, `nav-climb`, `nav-descend`
- Verifies cell match via `mc-status`

## Planning Notes

- Requires navigation history to be maintained by nav tools
- If recovery fails, consider `mc-place-until-supported` or broader replanning

## Example

```json
{"type":"nav-backtrack","max_targets":3,"out":"$recovery"}
```

Overview

This skill attempts to return the robot to a recently known safe navigation cell by replaying bounded local motions. It inspects the stored navigation history, selects safe past poses, and tries atomic primitives to reach one of them. The goal is a fast, local recovery without full replanning.

How this skill works

The skill reads world_state("nav") history and picks up to max_targets safe entries. For each candidate it issues a nav-turn followed by a single motion primitive: nav-move, nav-climb, or nav-descend. After executing a primitive it verifies the robot reached the expected cell using mc-status and reports the recovered pose and method.

When to use it

After a minor localization drift or small collision where a recent safe pose exists
When global replanning is too slow but a local undo may restore safety
If sensors report being off the expected map cell but a prior safe cell is known
When the robot is blocked on a small obstacle and a reverse step or descent may help
During runtime recovery before escalating to manipulation or large replan actions

Best practices

Maintain frequent nav history so safe targets are recent and reachable
Set max_targets to a small number (1–3) to keep recovery bounded and fast
Run mc-status after recovery to confirm exact cell match and yaw
If nav-backtrack fails, follow with place-until-supported or a global replan
Prefer this skill for short, local corrections rather than long-distance returns

Example use cases

Robot slightly nudged off course in a corridor: backtrack to last safe cell and continue
Failed grasp knocked the base; attempt a single-step recover to the previous cell
Descending a stair caused misalignment: try a controlled descend/recover step
Localization jump to a nearby cell: revert to the prior verified cell to stabilize
Blocked by low obstacle: attempt a climb or step back to a previously known safe pose

FAQ

What does the skill return on success?

It returns a summary, the recovered {x,y,z,yaw}, the method used (step, climb, or descend), and final yaw.

Why would recovery fail?

Failures include no nav history, no safe targets, primitives failing, or targets being unreachable; check mc-status and consider broader replanning.