Compass Doctor

You produce a diagnostic snapshot of a COMPASS dev environment and report what's working and what's broken. Read-only by design — you report problems but never auto-fix them. Once you've identified the root cause, point the user at the specialty skill that owns the fix.

This skill is the place users land when training "just won't start" or something obscure breaks. The goal is to surface the actual root cause in one screen, not to chase the symptom.

When NOT to use this skill

• The user knows what they want to do (train, evaluate, etc.) and just needs the workflow → /compass.
• The user wants to add a robot platform → /compass-newembodiment.
• A specific error message has a clear fix in the handbook → quote the relevant page; debug isn't needed.

Workflow

Step 1: Run the diagnostic script

The skill bundles scripts/compass_status.sh which runs all checks in parallel and prints a markdown table:

# dangerouslyDisableSandbox: true (script touches nvidia-smi)
bash <SKILL_BASE_DIR>/scripts/compass_status.sh

Output looks like:

| Status | Check | Detail |
|---|---|---|
| ✓ | Container | compass-rl up |
| ✓ | Activated shell | shim dir on PATH |
| ✓ | GPU | NVIDIA H100 80GB HBM3, 79980 MiB |
| ✓ | Base ckpt | ./assets/x_mobility.ckpt (1.2G) |
| ✓ | USDs | 8 entries in ./assets/usd/ |
| ✓ | Recent log | /tmp/isaaclab/logs/2026-05-08_14-23-02 |

For deeper diagnostics (slower, ~30s — runs Isaac Sim init headless to surface kit-init errors that don't show up in the quick check):

bash <SKILL_BASE_DIR>/scripts/compass_status.sh --deep

For checkpoint-specific issues (verifies a .pt file is a valid torch checkpoint and not corrupted):

bash <SKILL_BASE_DIR>/scripts/compass_status.sh --ckpt <PATH_TO_CKPT>

Step 2: Interpret the output

The table is the report; just relay it to the user. Then add a one-paragraph interpretation: which row is the root cause, and what to do about it.

Step 3: Recommend the next skill

Don't try to fix the issue yourself — different fixes belong to different skills:

Anti-pattern guard: don't run fixes yourself. The user benefits from understanding what went wrong; running fixes blind hides root causes.

Common patterns

"Training crashed silently"

Look for the most-recent kit log:

find ~/.local/share/ov/pkg/isaac-sim-* -name "kit_*.log" 2>/dev/null | head -1 | xargs tail -100

Common silent-crash causes:

• GPU OOM (look for "out of memory" / "CUDA error" near the tail).
• USD asset missing (look for "Failed to load" / file-path lines).
• Quaternion convention mismatch on a custom embodiment (look for "wxyz" / "xyzw").

"Pre-flight passes but python run.py … still errors"

Confirm the user is in an activated shell. The script checks PATH for the shim dir but a user can run scripts in any shell — verify with:

which python
# Should resolve to a /tmp/compass-shims.* path

If which python resolves to /usr/bin/python or similar, the shell isn't activated even if other env vars suggest it is.

"OSMO submission fails on osmo workflow submit"

That's an OSMO-side issue, not a local one. Check:

test -n "${WANDB_API_KEY:-}" && echo "WANDB_API_KEY set" || echo "WANDB_API_KEY MISSING"
test -n "${HF_TOKEN:-}" && echo "HF_TOKEN set" || echo "HF_TOKEN MISSING"
test -n "${COMPASS_OSMO_REGISTRY:-}" && echo "registry set" || echo "registry MISSING (or pass --image)"

If all set, route the user to /compass (OSMO submission section in that skill body).

Key File Locations