| name | ratchet-debug |
| description | Collect Ratchet local pipeline debug evidence. Use when a run is failed, stuck, stale, stopped, missing outputs, has confusing LLM behavior, or needs local evidence from pipeline traces, events.jsonl, worker.log, raw LLM artifacts, and a debug bundle directory. |
| argument-hint | [run-id] |
| allowed-tools | Bash, Read |
Ratchet Debug
Collect local evidence before inferring pipeline behavior. This skill is not a
repair workflow; use its output and bundle path as evidence for the invoking
agent to decide the next action.
Keep setup and execution in one Bash block so RATCHET_DIR, env vars, and an
optional run id stay in scope.
RATCHET_DIR="${RATCHET_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cat ~/.local/ratchet/plugin-root 2>/dev/null)}}}"
set -a && . "$RATCHET_DIR/.env" 2>/dev/null && set +a
RUN_ID="${RUN_ID:-}"
if [ -n "$RUN_ID" ]; then
uv run --directory "$RATCHET_DIR" ratchet debug --run-id "$RUN_ID"
else
uv run --directory "$RATCHET_DIR" ratchet debug
fi
ratchet debug auto-selects a run when no run id is supplied. It first selects
the newest failed run or an active run that has exceeded the staleness threshold;
if neither exists, it selects the newest recent run. Local debug evidence does
not require provider auth.
The command prints run evidence and writes a raw local bundle directory. Use the
reported Bundle dir path when handing off evidence.
Bundle contents include snapshot.json, status.json, manifest.json,
worker.log, events.jsonl, llm/, and related session files when present.
If the bundle directory already exists, Ratchet leaves it unchanged and reports
that it skipped creation.
For exact log contents, use the path reported by ratchet debug or run:
uv run --directory "$RATCHET_DIR" ratchet pipeline-logs --run-id <RUN_ID> --tail 160
For machine-readable evidence:
uv run --directory "$RATCHET_DIR" ratchet debug --run-id <RUN_ID> --json
