triggers:
  positive:
    - phrase: In our existing robot-navigation app, Nav2 plans a path but the robot never receives velocity commands. Diagnose it.
    - phrase: Explain how AMCL localization differs from SLAM in Nav2.
  negative:
    - phrase: Help me map a simulated environment, localize a mobile robot, and navigate to a goal.
      expect: architect
tasks: []

# When navigation fails

Start with the symptom that is actually present. Move upstream only when the
current link has evidence.

## The stack is unavailable or inactive

- Missing navigation actions point to bringup or lifecycle state, not planner
  tuning.
- If several managed nodes shut down together, find the first node that failed.
  The later transitions are usually fallout.
- If activation waits on a frame, map, or sensor, follow that missing input
  instead of forcing the node active.

## The pose is missing or stale

- Separate a broken transform chain from an old transform. Both can look like
  a missing pose to costmaps and actions.
- Check that every node uses the intended clock and that simulation time is
  advancing. Thread one `use_sim_time` launch value through every participating
  node; copied literals can silently diverge when the launch argument changes.
- Identify who owns each transform. AMCL and SLAM are alternative owners of
  `map -> odom`, not two publishers to run together.
- When `robot_localization` owns `odom -> base_link`, verify that TF publication
  is enabled and that `world_frame` matches the intended continuous odometry
  frame. Do not leave a Gazebo TF bridge publishing the same transform.
- With AMCL, distinguish “no initial pose yet” from a localizer that received a
  pose and still cannot publish one.

## A costmap has no useful data

- An empty global costmap points first to its map and transform inputs.
- An empty local costmap points first to its observation topics, frames,
  freshness, and QoS.
- A costmap full of obstacles points to footprint, inflation, clearing, or
  sensor interpretation. Confirm which layer contributes the cells before
  tuning it.

## A goal is rejected or aborted

- Rejected before planning: inspect action availability, lifecycle state, goal
  frame, and pose validity.
- Aborted without a path: inspect planner feedback and the global costmap.
- Aborted during execution: inspect controller feedback, recovery behavior,
  and the local costmap rather than treating every abort as a planning failure.
- Confirm that the goal is free space in the map frame. A valid world-frame
  coordinate is not automatically a valid map-frame goal.

## A plan exists but the robot does not move

- If no motion command appears, inspect the controller's rejection reason,
  footprint, local costmap, progress checker, and goal checker.
- If commands appear and are then zeroed, trace velocity smoothing, collision
  monitoring, safety, and command arbitration in order.
- A path visible in a viewer proves planning only. It does not prove control or
  actuation.

## Velocity exists but the base remains still

- Compare the publisher and subscriber topic names and message types.
- Follow remaps through every mux, smoother, safety node, bridge, and base
  driver. Do not stop at the first `cmd_vel` topic with traffic.
- Check the base's own state, limits, and stop conditions. Once a valid command
  reaches the driver, the fault is outside Nav2.

## The failure is intermittent

- Compare timeouts with measured publication periods, jitter, and startup load.
  A timeout equal to the nominal period has no margin.
- Correlate lifecycle or bond failures with the first stalled or crashed node,
  not the loudest shutdown log.
- Reproduce one failure at a time. Concurrent simulators or duplicate
  localizers can create convincing but unrelated symptoms.

---
name: navigation
description: Configure, extend, and debug Nav2 in an existing robot app; explain navigation concepts. New mapping/localization/navigation demos start with architect.
---

# Navigation

Treat Nav2 as a **navigation chain**. Find the first link whose evidence is
wrong.

## Start from the robot

- For a new app or first demo, read [architect](../architect/SKILL.md) before
  scaffolding or installing a navigation stack. It finds the saved apps checkout
  and selects a compatible baseline, even from outside the Robium workspace.
  If that selection already happened, continue here. Existing-app fixes and
  navigation explanations do not need onboarding.
- Read the running system and its repository before proposing a new stack.
- Identify the ROS distribution, installed Nav2 version, launch topology, and
  parameter files from the environment itself.
- Note the robot's motion model, footprint, sensors, frames, command interface,
  and whether it is using SLAM or a saved map.
- Start from the robot vendor's matching configuration. Change only what the
  application has outgrown.

## Trace the chain

- **Environment:** the installed packages, launch files, parameters, and
  running graph describe the same stack.
- **Pose:** clock and transforms are fresh; one localizer owns `map -> odom`;
  odometry owns the path from `odom` to the robot base.
- **World:** the map and live sensors reach both costmaps in frames they can
  transform.
- **Plan:** the navigation action accepts the goal and the planner produces a
  path in the intended frame.
- **Control:** the controller receives that path and can produce a valid motion
  command for the robot's kinematics and footprint.
- **Base:** command topic, message type, smoothing or safety nodes, and base
  driver agree end to end.
- Change the first broken link, then re-check what depends on it.

## Go deeper only when needed

- If navigation is failing and the broken link is unclear, read
  [FAILURES.md](FAILURES.md).
- If the stack is TurtleBot3 on ROS 2 Jazzy with Gazebo Harmonic, read
  [TURTLEBOT3-JAZZY-GAZEBO.md](TURTLEBOT3-JAZZY-GAZEBO.md) before changing its
  launch or parameters.
- For distribution-sensitive parameters, behavior trees, or custom Nav2
  plugins, inspect the matching installed source and current official Nav2
  documentation.
- Reach for ROS 2 guidance when the evidence points to discovery, QoS, TF, or
  package wiring; Gazebo guidance for simulation, spawning, sensors, or
  bridges; and RViz2 or Foxglove guidance for viewer behavior.

## Done

- Verify the changed link and the user-visible outcome: the intended goal
  completes on the actual robot or representative simulation.
- If the chain cannot be completed, name the first unsupported link and the
  evidence still needed.

# TurtleBot3 + ROS 2 Jazzy + Gazebo Harmonic

Use this card only when the robot, ROS distribution, and simulator all match.
Treat every value below as observed evidence, not a default to copy blindly.

## Start from the matching platform

- Use the model-specific parameters from `turtlebot3_navigation2` before the
  generic `nav2_bringup` parameters. The tested Jazzy package carried
  TurtleBot-specific kinematics, footprint, collision monitoring, and velocity
  settings that the generic file did not.
- Keep the simulation model, bridge configuration, robot description, and Nav2
  parameters matched to the same TurtleBot model.
- Inspect the installed package before relying on filenames or defaults. The
  upstream TurtleBot repositories use distribution branches and continue to
  evolve.

Official starting points:

- [TurtleBot3 e-Manual](https://emanual.robotis.com/docs/en/platform/turtlebot3/quick-start/)
- [ROBOTIS TurtleBot3](https://github.com/ROBOTIS-GIT/turtlebot3)
- [ROBOTIS TurtleBot3 simulations](https://github.com/ROBOTIS-GIT/turtlebot3_simulations)
- [Nav2 documentation](https://docs.nav2.org/)

## Interface contract observed by Robium

- Gazebo publishes `/clock`; every node participating in navigation uses that
  clock.
- The tested Burger bridge subscribed to `/cmd_vel` as
  `geometry_msgs/msg/TwistStamped`. A plain `Twist` publisher had no matching
  subscriber and did not move the robot.
- The tested TurtleBot navigation parameters already enabled stamped velocity
  output in each command-producing Nav2 section. Starting from generic Nav2
  parameters lost that alignment.
- Burger Cam and Waffle Pi preserved the application's movement, odometry, TF,
  lidar, IMU, and camera interfaces when their matching model, bridge, and
  description were selected together.
- The tested Waffle Pi profile used a `0.15 m` Nav2 robot radius. Re-read the
  matching installed profile before applying that value to another model.

## Proven gotchas

- **Command type:** on the tested Jazzy Burger stack,
  `geometry_msgs/msg/TwistStamped` moved the robot and plain `Twist` did not.
  Trace the live publisher/subscriber types before changing Nav2 output.
- **Collision-source freshness:** the tested Burger lidar published at `5 Hz`
  while collision monitoring used `source_timeout: 0.2`. Normal jitter made
  scans stale and commands were zeroed. `1.0` worked in that run; the reusable
  rule is to measure the source and leave real margin above its period.
- **Duplicate SLAM:** Jazzy `nav2_bringup` with `slam:=True` already launched
  `slam_toolbox` in the tested package. Starting another SLAM launch produced
  competing lifecycle owners and immediate navigation failures. Inspect the
  actual launch graph before adding a localizer.
- **Container stalls:** on a constrained Docker Desktop host, an approximately
  `8 s` activation stall exceeded a `4 s` lifecycle bond timeout and shut the
  stack down. Setting `bond_timeout: 0.0` allowed that experiment to run but
  disabled bond failure detection; fix resource pressure or measure startup
  behavior before accepting that tradeoff.
- **Launch substitutions:** the tested TurtleBot parameter file contained
  `$(find-pkg-share ...)` behavior-tree paths. A custom launch passing the YAML
  directly left those expressions literal; loading it through a substitution-
  aware `ParameterFile` resolved them.
- **Map coordinates:** goals authored from Gazebo world coordinates did not
  automatically match the SLAM map frame. Use TF or select goals from the map;
  do not generalize the tested spawn-offset arithmetic to rotated frames.
- **Goal clearance:** several failed waypoints were inside or too near world
  geometry. Confirm clearance against the map and footprint before changing
  planner tolerances.

## Model and application evidence

- The original Burger/Jazzy/Harmonic run completed mapping and two saved-map
  Nav2 goals with stamped velocity output:
  [2026-07-10 nav-trial](../../learnings/2026-07-10.md).
- A later Waffle Pi application preserved the TurtleBot sensor and control
  contract across several Gazebo worlds:
  [2026-08-14 indoor-navigation](../../learnings/2026-08-14-indoor-navigation.md).
- The renamed Robot Navigation application completed the full chain from
  Gazebo lidar through mapping, map save, AMCL, and a Nav2 return goal:
  [2026-08-16 robot-navigation](../../learnings/2026-08-16-robot-navigation.md).

Re-check the upstream packages whenever the ROS distribution, TurtleBot model,
simulator, or installed package version changes. Add another platform card only
after that combination completes a real navigation run.