helmor-debug-operate

Helmor Debug Operate

Use this skill to operate and debug a running Helmor dev build through Tauri MCP with the least possible exploration. It is the visual/runtime counterpart to helmor-cli: prefer Tauri MCP for webview UI, screenshots, CSS, accessibility, and IPC tracing; prefer helmor-cli for terminal-first data inspection or workspace orchestration.

Examples below use bare tool names such as driver_session; call the same tool through whatever namespace the runtime exposes.

References

Read these only when needed:

• references/verified-recipes.md for action-specific recipes that have passed three consecutive Tauri MCP verification attempts.
• references/ui-map.md for selectors, Settings panels, Inspector/Editor preconditions, and destructive-action boundaries.

Ground Rules

• Treat every action as real user input against the active app. Do not send prompts, close sessions, archive/delete workspaces, stop streams, or mutate settings unless the user asked for that outcome or it is necessary for the verification.
• Use the Tauri MCP bridge only for Helmor desktop debugging. Do not switch to Chrome DevTools, Browser, Playwright, or /agent-browser unless the user explicitly asks for another surface.
• Require a debug Tauri build. The bridge is absent in release builds. If connection fails, ask the user to run bun run dev or call get_setup_instructions only when bridge setup itself is suspect.
• Default to port: 9223 and windowId: "main".
• Re-run webview_dom_snapshot after every meaningful UI change. ref=eN handles are per-snapshot and expire after DOM changes.
• Prefer accessibility snapshots for finding controls, but fall back to structure snapshots and read-only DOM rect inspection when accessibility support is unavailable.
• Prefer UI operations for end-to-end validation. Do not use the Tauri MCP tool ipc_execute_command for Helmor app commands such as list_workspace_groups, reveal_workspace_in_main_window, or debug_list_terminal_buffers: the current bridge returns Unsupported Tauri command because dynamic app-command execution is not implemented there. Use the verified app-command helper in Call App Commands instead.
• Do not use webview_execute_js to dispatch synthetic user events. Use it only for read-only, JSON-serializable inspection when MCP tools cannot answer the question.
• Exception: Helmor's composer is a Lexical contenteditable, not a native input. If webview_keyboard type fails with the current bridge, document.execCommand("insertText", false, text) after real MCP focus/click is the last-resort smoke-test input path. Label it as a fallback and verify visible state afterward.
• If you start ipc_monitor, always stop it before finishing, even if the task fails.
• Save screenshots or scratch logs under .agent-contexts/<task-slug>/ when working inside this repository.
• If a Settings dialog appears stuck visible with data-state="closed", press Cmd+, to reopen it, then Escape to close. Verify document.querySelectorAll('[role="dialog"]').length === 0 and main[aria-hidden] is absent.
• If webview_execute_js or console log reads start timing out while screenshots and driver_session status still work, restart only the MCP driver session (driver_session stop appIdentifier=9223, then driver_session start port=9223). Do not restart the Helmor dev build unless the bridge cannot reconnect.
• If you launch a disposable app with HELMOR_DATA_DIR for validation, create both the data dir and its run/ subdir first. Missing run/ can make the UI sync socket fail to bind, leaving backend mutations invisible until you force a reveal or restart.
• Treat this skill as an operation hint, not an authoritative source of truth. The local UI can drift ahead of these recipes. If a recipe fails three times, stop repeating it mechanically: take a fresh screenshot/snapshot, reason from the visible UI, and inspect the relevant code if needed.
• Keep this skill self-improving by proposal, not silent mutation. When you discover a better path, missing pitfall, stale selector, or unverified workaround, record a candidate update under .agent-contexts/<task-slug>/skill-update-candidates.md with the scenario, failing attempts, evidence, proposed recipe, and verification status. Ask the user before editing this skill unless the current user request explicitly asks you to update it.