agentleFS
puritysbpuritysb/AgentDeck/.agents/skills/sdc-diagnose/SKILL.md

sdc-diagnose

Skill299 starsChanged 14 days agoMITView on GitHub

Diagnose AgentDeck Stream Deck/PTY option synchronization, cursor state, hook ingestion, and bridge state-machine issues. Collects diagnostics, searches known failure patterns, adds focused regression tests, and verifies with pnpm tests.

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 21
  2. Distinctive:

    If access fails, follow AGENTS.md Agent working agreements for execution-policy failures.

    line 29
  3. Distinctive:

    Add focused tests near the subsystem under change:

    line 83
  4. Distinctive:

    Run the narrowest useful tests first, then broaden when shared behavior changed:

    line 109
  5. Distinctive:

    Check that all existing tests pass, new regression tests pass, and there are no TypeScript errors.

    line 117

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

2c. Stale Options

option_prompt with missing or non-contiguous indices.

Pattern: option_prompt indices=[0,1,3] (missing 2)
Root cause: Buffer corruption or partial redraw parsed as complete
Fix: Buffer tail re-parse with debounce

2d. Action Dispatch Race

select_option overlapping rapid state transitions.

Pattern: select_option ... state AWAITING->PROCESSING->AWAITING (rapid cycle)
Root cause: Enter sent before arrow navigation completes
Fix: Proportional delay (A4) — 50 + |delta| * 20ms

2e. ANSI Cursor Invisible

Terminal keyboard input without a corresponding cursor_update for >500ms.

Pattern: (arrow key in terminal) ... no cursor_update for >500ms
Root cause: ink repositions cursor via ANSI sequences without ❯ in chunk
Fix: ANSI reposition detection (A1) — re-parse buffer on small non-❯ chunks

2f. Codex Hook Gap

Missing codex_user_prompt_submit, codex_tool_start, codex_tool_end, or codex_stop in daemon hook logs.

Pattern: Codex session active but lifecycle hooks absent from hook log
Root cause: ~/.codex/config.toml hooks not installed/migrated, or fence corrupted
Fix: re-run `agentdeck codex` (installs/migrates) or inspect installCodexHooksIfNeeded

Step 3: Add Regression Tests

Add focused tests near the subsystem under change:

  • Parser / state-machine / cursor issues: bridge/src/__tests__/cursor-sync.test.ts, state-machine.test.ts, or parser tests.
  • Codex hook issues: hooks/src/__tests__/codex-install.test.ts, bridge/src/__tests__/state-machine.test.ts, or the Codex APME adapter tests.
  • Apple timeline/rendering issues: apple/AgentDeckTests/.

Template (cursor desync, vitest):

it('reproduces cursor desync from journal entry', () => {
  const sm = bootToIdle();
  sm.handleParserEvent('option_prompt', {
    options: [/* options from journal */],
    navigable: true,
    cursorIndex: 0,
  });

  sm.updateCursorIndex(/* target */, 'optimistic');
  vi.advanceTimersByTime(/* gap from journal */);
  sm.updateCursorIndex(/* stale PTY value */, 'pty');

  expect(sm.getCursorIndex()).toBe(/* expected */);
});

Step 4: Run & Verify

Run the narrowest useful tests first, then broaden when shared behavior changed:

cd "$(git rev-parse --show-toplevel)"
pnpm test
pnpm -r exec tsc --noEmit

Check that all existing tests pass, new regression tests pass, and there are no TypeScript errors.

Step 5: Report

## Diagnostic Report

### Issues Found
1. [PATTERN]: Description
   - Journal entries: [timestamps]
   - Expected: X
   - Actual: Y
   - Fix: [A1/A2/A3/A4/A5/codex] — description

### Tests Generated
- <file>: N new tests
- Regression coverage: [patterns covered]

### Verification
- pnpm test: PASS/FAIL
- TypeScript: PASS/FAIL

### Recommendations
- [Any additional fixes or monitoring suggestions]

Key Files Reference

FilePurpose
bridge/src/output-parser.tsPTY output parsing, cursor detection
bridge/src/state-machine.tsState transitions, cursor authority
bridge/src/index.tsBridge wiring, command handlers
bridge/src/__tests__/cursor-sync.test.tsCursor sync test suite
hooks/src/codex-install.tsCodex lifecycle hook installer (hook-gap issues)
~/.agentdeck/journal/Event journal files
/tmp/sdc-debug.logDebug log (when -d flag used)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.