AgentDeck: Skill for Claude Code

AgentDeck Diagnostic Skill

Canonical diagnostic procedure for AgentDeck bridge synchronization issues between device displays and agent terminals (cursor desync, false idle, stale options, action dispatch races, hook ingestion gaps, state-machine regressions). This file is the single source of truth — .claude/skills/sdc-diagnose is a tracked directory symlink to this skill.

Step 1: Collect Diagnostic Data

From the repo root, try the live bridge first. Start narrow: ~100 journal entries, filtered to the event types the Step 2 patterns use. Widen (--tail 300, then drop the filter) only when the window does not contain the failure.

cd "$(git rev-parse --show-toplevel)"
EVENTS='state_change|hook|error|option_prompt|navigate_option|cursor_update|select_option|idle|codex_'
agentdeck diag --tail 100 2>/dev/null | grep -E "$EVENTS" | tail -100 \
  || echo "Bridge not running (or no matching events) — using journal files directly"

If the bridge isn't running, read journal/log files directly, with the same filter:

ls -t ~/.agentdeck/journal/*.jsonl 2>/dev/null | head -3
ls -t ~/.agentdeck/journal/*.jsonl 2>/dev/null | head -1 | xargs tail -n 400 | grep -E "$EVENTS" | tail -100
grep -E "$EVENTS" /tmp/sdc-debug.log 2>/dev/null | tail -100 || echo "No debug log found"

If access fails, follow AGENTS.md Agent working agreements for execution-policy failures. Treat unreadable diagnostics as unknown, not proof that the bridge is stopped.

Step 2: Analyze for Known Failure Patterns

2a. Cursor Desync

navigate_option followed by a stale cursor_update with conflicting indices.

Pattern: navigate_option cursor=X->Y ... cursor_update cursorIndex=X (reverted)
Root cause: PTY confirmation overwrites optimistic update
Fix: cursor authority system (A3) — optimistic suppresses PTY within 200ms

2b. False Idle

option_prompt followed by idle within 500ms.

Pattern: option_prompt (N options) ... idle_detected (< 500ms gap)
Root cause: Small chunk with "❯ No" misclassified as idle prompt
Fix: Semantic idle check (A2) — only "❯" or ">" as sole non-ws content