helmor-debug-loop

---
name: helmor-debug-loop
description: Autonomous local-development debugging loop for Helmor bugs. Use when the user asks an agent to reproduce, diagnose, instrument, fix, or verify a Helmor local dev build issue using repeated local UI simulation, temporary logging, Tauri MCP/towery MCP, screenshots, DOM/accessibility snapshots, IPC traces, console/system logs, terminal/run-script logs, or multi-attempt verification. This skill coordinates with $helmor-debug-operate for operating the running desktop app.
---

# Helmor Debug Loop

Use this skill to drive a bounded reproduce -> instrument -> inspect -> fix -> verify loop for Helmor local-dev bugs. Always use `$helmor-debug-operate` for actual local app control through Tauri MCP; this skill owns the debugging strategy and evidence discipline.

## Core Loop

1. Define the suspected behavior, expected behavior, and success signal in one or two sentences.
2. Reproduce through `$helmor-debug-operate` with real UI actions when possible. Start with screenshots, DOM/accessibility snapshots, IPC monitor, console/system logs, and terminal buffers.
3. If evidence is insufficient, add the smallest temporary log or probe with a unique prefix such as `[debug-loop:<slug>]`, rerun the flow, then remove or justify the probe before finalizing.
4. Analyze the evidence before editing product code. Prefer a narrow fix that explains the observed signal.
5. Verify the fix with the same user path. For user-visible flows, require three consecutive successful runs unless the user explicitly lowers the bar.
6. Produce an evidence pack under `.agent-contexts/<task-slug>/` with repro attempts, logs, screenshots, IPC, fix summary, and remaining uncertainty.

## Fault Tolerance

- If you cannot reproduce after three distinct attempts, do not invent a failure. Mark the state as `not reproduced`, preserve evidence, inspect code paths that should have fired, and report the most likely missing precondition.
- If the bug is flaky, run at least three attempts and compare evidence. Treat intermittent pass/fail as a valid finding, not a failure of the loop.
- If Tauri MCP cannot connect, use `$helmor-debug-operate` recovery steps. If the bridge remains unavailable, fall back to static code analysis and terminal tests, and label UI verification as blocked.
- If a skill recipe fails three times, follow `$helmor-debug-operate` stale-skill rules: reason from fresh screenshots/DOM/code, record a candidate skill update, and ask before editing that skill unless the user explicitly requested it.
- If adding logs risks exposing secrets, log shape/count/state only. Never print access tokens, credentials, API keys, cookies, or private account details.
- If verification cannot be run safely because it would mutate durable user data, switch to a disposable workspace/session or stop and state the risk.

## Evidence Sources

Use the available signals in this order:

- Terminal buffers: use `$helmor-debug-operate`'s **Call App Commands** helper to run `debug_list_terminal_buffers`, then `debug_read_terminal_buffer` with the returned raw `scriptType`.
- UI state: screenshot plus accessibility or structure snapshot.
- IPC: start monitor, perform one action, capture filtered commands/events, then stop monitor.
- Logs: Tauri console/system logs, sidecar JSONL logs under the dev data dir when relevant.
- Code probes: temporary logs with unique prefixes, guarded by debug context when possible.

Read `references/debug-loop.md` when the task needs the full loop checklist or when reproduction fails. Use scripts in `scripts/` to summarize logs and build evidence packs instead of pasting raw dumps into the chat.