From d6147bf6a9eda77cc360f4c7842e919cdf0c66a8 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Fri, 26 Jun 2026 12:42:30 +0200 Subject: [PATCH] =?UTF-8?q?skill(debug):=20positive=20framing=20=E2=80=94?= =?UTF-8?q?=20failure=20modes=E2=86=92resolution=20patterns,=20broken?= =?UTF-8?q?=E2=86=92errors?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .agent/skills/debug/SKILL.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.agent/skills/debug/SKILL.md b/.agent/skills/debug/SKILL.md index 912c5dd..76af6ca 100644 --- a/.agent/skills/debug/SKILL.md +++ b/.agent/skills/debug/SKILL.md @@ -1,6 +1,6 @@ --- name: debug -description: Debug Clawdie agent issues on the current FreeBSD host runtime. Use when the agent is not responding, the service is crashing, Telegram messages go unanswered, pi subprocesses fail, or when verifying the live runtime shape. Covers host service management, logs, optional jail state, memory DB reachability, and common failure modes. +description: Debug Clawdie agent issues on the current FreeBSD host runtime. Use when the agent is not responding, the service is restarting, Telegram messages go unanswered, subprocesses stall, or when verifying the live runtime shape. Covers host service management, logs, optional jail state, memory DB reachability, and common resolution patterns. --- # Clawdie Agent Debugging (FreeBSD host runtime) @@ -74,7 +74,7 @@ tail -50 logs/clawdie.error.log ls groups/*/logs/agent-*.log | tail -5 ``` -When a specific run failed, read the newest per-run log directly: +After a run completes with an error, read the newest per-run log: ```bash ls -t groups/*/logs/agent-*.log | head -3 @@ -133,7 +133,7 @@ command -v pi pi --version ``` -Common causes: +What to check first: - provider key missing or expired - `PI_TUI_BIN` points at a dead path @@ -177,7 +177,7 @@ grep -E 'fatal|error|exit|SIGTERM|SIGKILL' logs/clawdie.log | tail -20 grep '409\|duplicate\|conflict' logs/clawdie.log | tail -10 ``` -Temporarily stop the service to break the loop, fix the root cause, then +Pause the service to stop the restart loop, resolve the underlying issue, then restart. ### Watchdog or controlplane resets the agent @@ -187,7 +187,7 @@ grep -i watchdog logs/clawdie.log | tail -10 grep -i controlplane logs/heartbeat.log | tail -20 ``` -### Build broken after a code change +### Build errors after a code change ```bash npm run build @@ -217,7 +217,7 @@ tail -10 logs/clawdie.error.log ## 6. Optional jail shell access -Only for installs that actually use jails for the thing you are debugging: +For jail-backed installs: ```bash sudo bastille console db @@ -272,7 +272,7 @@ ls groups/main/logs/ ls groups/main/ipc/ 2>/dev/null ``` -Run logs are disposable debugging artifacts: +Run logs are temporary diagnostic files: ```bash rm -f groups/main/logs/agent-*.log