/debug-ios

name: debug-ios
description: Self-debug iOS app end to end — verify device/simulator, devtool, log daemon work, plan root-cause investigation, drive app via synthetic taps/gestures while capture timestamped logs, report findings back to human. Use whenever user report bug, crash, hang, stuck spinner, wrong behavior in iOS app, or ask reproduce/investigate/diagnose something on iOS, check device/simulator logs, or drive UI without touch phone self — even if no say "debug" explicit (e.g. "the reconnect spinner never stops", "workspace card does nothing when tapped", "why did it crash on my phone", "check what's happening on my iPhone").
allowed-tools: Bash, Read, Edit, Grep, Glob, AskUserQuestion, Agent

Debug iOS

Autonomous iOS debug loop: verify environment, plan investigation, drive app while capture logs, report back. Build on `docs/DEVTOOL.md` (in-app tap/touch driver, iOS + Android), `scripts/ios-log.sh daemon` (background log capture queryable by time range), and `scripts/ios-log.sh wait` (poll for expected log line, no sleep-and-hope).

Invoke with bug description + optional flags: `/debug-ios <bug description> [--direct] [--no-devtool] [--perf]` — see "Flags" below for what each change.

At a glance

0. **Verify** — device connect, log daemon capture fresh timestamp output, devtool reachable (built `--devtool --debug`). 1. **Plan** — hypothesis from read code first + ordered action steps + logs to add. 2. **Loop** — action → capture → evaluate → next, until root cause confirm or the first failed attempt requires more information (see below). 3. **Summary** — report to human: what wrong, what tried, the fix, cleanup status, assumptions, recommendations, new concepts, proposals.

Each phase run as own subagent by default (`--direct` inline instead). Iron Law + Output hygiene apply every phase — read those next.

Iron Law

**NO FIX WITHOUT VERIFIED ROOT CAUSE. NO "DONE" WITHOUT RE-OBSERVE FIX WORKING.** Never assume — every hypothesis check against real log line or real screenshot/element query before act on it. Can't verify, say so and ask for the missing information; don't guess-and-ship. Token cost not reason to stop loop — wrong fix cost user far more than another verify pass.

Flags

• `--direct` — run every phase (verify/plan/loop/summary) inline in main

conversation instead of delegate to subagents. Use for quick, narrow bug where overhead of spawn agents not worth it. Default is subagent-delegated (see "Why subagents" below).

• `--no-devtool` — skip action-step loop entirely; only add logs, ask

human reproduce manually, read back capture. Use when iOS devtool not built into current app binary and rebuild not wanted yet.

• `--perf` — this performance investigation, not correctness bug.

Switch Phase 2 logging to per-frame + aggregation-key pattern instead of state-change logging — see `references/perf-mode.md`.

Why subagents

Each phase below dispatch to subagent by default (`Agent` tool, one per phase, foreground since each phase output gate next). Subagent get **plan + expected result**, do work (shell commands, log reads, devtool calls), return **findings + logs tried + summary** — not transcript. Keep main conversation context to "what learn and what next," not "every curl call and grep." Main agent (you, in parent conversation) read each subagent report, decide next action — you accumulate cross-phase picture, not any single subagent.

`--direct` collapse this: you do work self in main thread. Use when spawn agent cost more than save.

Output hygiene

Apply everywhere in this skill — subagent reports, `--direct` mode, every phase. Subagent isolate verbose work in own context only help if **returned summary** don't just re-paste verbosity into parent conversation; that the actual leak, not tool calls self.

• **Never paste raw JSON into response.** `devtool.sh elements` return

full frame dump — parse it, state 1-3 field that matter ("`ws-card-0` at x=51,y=345"), not payload. Default to `devtool.sh list` (already concise table) for routine "what's on screen" checks; reach for raw `elements` only when need exact coordinates for script, and even then quote only relevant entry.

• **Never paste more than ~10-15 raw log lines.** `ios-log.sh query`/

`ios-log.sh wait` output real signal, but response to human should be "N lines matched `<pattern>`; relevant ones: ..." with just those lines — not full scrollback. Need scan more to find signal, do scanning, then report finding, not scan. Redirect wide captures to file if need grep repeatedly. `ios-log.sh wait` already return one line for exactly this reason — prefer over `ios-log.sh query` when have specific pattern in mind, not open-ended window to eyeball. Never `cat` raw capture file or forward unfiltered contents into final report; only include specific matched lines support the finding making.

• **Command output (build logs, `ps aux`, curl `-v`) summarize to

pass/fail + one relevant line**, not paste wholesale. Build either succeed or fail at specific step with specific error — that report, not scrollback.

• This hard rule for subagent reports specific: "findings + logs

tried + summary" (above) mean summary state what found, with short supporting quotes — not transcript replay, parent agent should not need re-summarize subagent already-verbose report.

Phase 0: Verify

Dispatch (or, with `--direct`, run inline):

1. **Device connect.** `idevice_id -l` must list UDID (physical device) or booted simulator must exist (`xcrun simctl list devices booted`). Neither, STOP, ask human which target use — don't guess.

2. **Log daemon, before devtool bridge — both platforms now.** Start daemon there launch app via `devicectl --console` (device) or `simctl launch --console` (simulator) — this **replace whatever instance already running**, on EITHER platform, so step must come before devtool bridge, or you'll bridge to proces