---

name: debug-app description: Use when the user has finished building a mobile app, started Metro with npm run dev, and wants the running app monitored for runtime errors AND silent failures (empty lists, blank screens, swallowed network errors) and fixed autonomously. Accepts a free-text symptom (e.g., /debug-app "todos not appearing on home screen") to drive persisted-log diagnostics — injects temporary console.log statements at data-path boundaries, reads the sanitized .powernative/metro-logs/ log, and cleans up logs after the root cause is fixed. Supports port/platform filtering, configurable clean-cycle and timeout limits, and watch-only --no-fix mode. Otherwise polls with a durable byte cursor, fixes inline or routes appropriately, verifies each fix from new output, and exits after the configured clean checks (default 3). Foreground loop — blocks the conversation while running. Run only after the app is loaded. user-invocable: true allowed-tools: Read, Edit, Write, Grep, Glob, Bash, AskUserQuestion, WebFetch, mcp__plugin_mobile-app_microsoft-learn__microsoft_docs_search model: sonnet

Plugin check: Run node "${PLUGIN_ROOT}/scripts/check-version.js" - if it outputs a message, show it to the user before proceeding.

📋 Shared instructions: shared-instructions.md — read first.

Debug App — Monitor & Fix

Monitor the running app through the project-local .powernative/metro-logs/ files written by metro.config.js, detect runtime and bundle errors, and fix them autonomously by editing the affected files (or routing to the right skill when the fix belongs in a domain like Dataverse schema or auth registration). For silent failures, inject temporary console.log statements at data-path boundaries, read only newly appended log bytes, then clean the traces after the root cause is fixed. Modeled on the upstream app-debugger.agent.md pattern — foreground loop, bounded polling, configurable clean-check/timeout exits, and optional watch-only operation.

Dev-client limitation: the standalone dev client sends app/runtime logs, React errors, host diagnostics, and Metro bundler output through Metro. The template's metro.config.js writes Metro terminal output and HTTP bundle failures into .powernative/metro-logs/; there is no separate device log source. Host diagnostics include strings such as [AuthProvider] MSAL init failed:, [bridge] fetch THREW for, [bridge] HTTP <status> for, [addAadAppToConnectionAcl] failed HTTP <status> for connection, [useConnectionRefs] could not verify connection ACLs; treating existing connections as setup-required, and [PAHost][ErrorBoundary] Unhandled JS error:.

Subcommands (parsed from $ARGUMENTS)

| Form | Behavior | |---|---| | /debug-app (no args) | Default — project-log-driven mode. Run Phase 0, discover valid project-local Metro sessions, select automatically when one is live or ask when several are live, then monitor the selected log. No host terminal ID is required. | | /debug-app "<symptom text>" | Symptom-driven mode (recommended when there's a user-visible problem). Free-text symptom such as "todos not appearing on home screen", "login button does nothing", "list empty after refresh". Run Phase 0 → Phase 0.5 (parse symptom → ask the user to reproduce/navigate → walk the likely data path from terminal traces) → enter monitor loop. Catches silent failures (empty lists, blank screens, swallowed errors) that pure log polling misses. | | /debug-app status | Discover all project-local Metro logs and print each valid session's project, platform, PID, port, start time, and log path. Mark the session referenced by the saved cursor when present, then print fixes and unresolved errors. Do NOT ask for a selection or enter the loop. | | /debug-app stop | Stop only the foreground debug loop and preserve .powernative/debug-app/ state. It does not stop Metro; the user owns the npm run dev process. | | /debug-app version | Print the installed mobile-app plugin name and version from ${PLUGIN_ROOT}/.plugin/plugin.json, then exit. |

Monitoring options

Options may follow the default command, a symptom, or status:

| Option | Meaning | Default | |---|---|---| | --working-dir <path> | App root containing package.json and metro.config.js. Relative paths resolve from the current shell directory. | Current shell directory | | --port <1-65535> | Monitor only the valid Metro session on this port. | Any port | | --platform <ios\|android> | Consider only sessions whose recent log identifies this platform. | Any platform | | --cycles <1-50> | Exit after this many consecutive clean observation intervals. | 3 | | --timeout <duration> | Maximum wall-clock monitoring time. Accept 30s–60m using s, m, or h. | 5m | | --no-fix | Watch-only mode: classify and report, but never edit project source/config, inject traces, install dependencies, regenerate files, or invoke a mutating handoff. Debug cursor/audit/health state still advances. | Fix enabled |

Examples:

/debug-app --port 8082 --platform ios
/debug-app "orders screen is empty" --cycles 10 --timeout 15m
/debug-app --no-fix --timeout 30m
/debug-app status --platform android
/debug-app status --working-dir ../my-mobile-app

Argument parsing:

1. Parse quoted text as one symptom value and parse recognized flags wherever they appear.
2. The first reserved token (status, stop, help, --help, -h, version, --version) selects the subcommand. stop, help, and version do not accept monitoring options. status accepts only --working-dir, --port, and --platform; reject symptoms, --cycles, --timeout, and --no-fix because it does not enter the loop.
3. After removing recognized options and their values, any remaining non-reserved text is the symptom and enables symptom mode.
4. Reject unknown flags, duplicate flags, missing values, invalid numbers, unsupported platforms, or more than one free-text symptom. Print the valid forms and exit without monitoring.
5. Normalize platform to lowercase. Convert timeout to timeoutSeconds; require 30 <= timeoutSeconds <= 3600. For monitoring and status, resolve workingDir to an absolute path from --working-dir or the current shell directory. Do not search parent directories. Require package.json and metro.config.js at that root; otherwise print the invalid path and stop before reading or writing project state. After validation, cd to workingDir once and reset it from the resulting absolute $PWD; every relative project path and command below runs from that directory.
6. Initialize:

   workingDir=<absolute app root>
   portFilter=<number|none>
   platformFilter=<ios|android|none>
   targetCleanCycles=<number, default 3>
   timeoutSeconds=<number, default 300>
   noFix=<true|false, default false>
   monitorStartedAt=<current ISO timestamp>
   

For help / --help / -h, print the subcommands and monitoring-options tables and exit.

Early-return subcommands:

• stop: if received while this foreground loop owns the conversation, clean up any injected traces using Phase 0.5.5 and exit at the next safe boundary. For a standalone stop invocation, report that no loop is active. Never stop Metro or delete .powernative/debug-app/ state.
• version / --version: read ${PLUGIN_ROOT}/.plugin/plugin.json, print <name> <version>, and exit without resolving a project or writing state. If the manifest is missing or malformed, report that the plugin version is unavailable and exit.
• status: validate workingDir, then execute only Phase 0.0 discovery through the status branch below. Do not run project preflight, create state files, ask for a session, initialize a baseline, or enter the monitor loop.

Tip — "play around then debug": Metro persists recent app output in .powernative/metro-logs/ even across chat/editor restarts. If something weird just happened, keep using the app normally, then run /debug-app or /debug-app "<what you saw>". The first cycle reads the latest persisted log window; subsequent cycles read only bytes appended after the saved cursor.

Core Principles

• Foreground autonomous loop — Once started, this skill owns the conversation until targetCleanCycles consecutive clean polls confirm the app is healthy, timeoutSeconds elapses, the user types stop, or the escalation rule trips. Do not run other skills concurrently — they'll queue behind the loop.
• Watch-only means no project mutation — With --no-fix, do not edit project source/configuration, inject diagnostic logs, install packages, regenerate schemas, switch accounts, or invoke a mutating skill. Continue to advance .powernative/debug-app/ cursor/audit/health state, classify errors, and provide the fix/handoff that would have been used.
• Run AFTER the app is loaded — Metro must be running through npm run dev and the simulator/device must have the app open. Phase 0 verifies that a live .powernative log exists; the skill stops cleanly if no app is detected.
• Native-only runtime target — The app must be loaded in a native dev client on a device or simulator; .powernative/metro-logs/ is the authoritative log source for that native session.
• No web or direct Metro probes — Do not use React Native Web, browser automation, curl, fetch, WebFetch, or any direct request to a Metro/localhost endpoint for runtime diagnosis. Read only the .powernative log and source files.
• No screen-by-screen verification — Do not crawl routes or validate every screen. In symptom mode, focus only on the user-reported workflow and the terminal/source evidence needed to diagnose it.
• One fix at a time — Fully resolve one issue (context → fix → type-check → reload → re-poll) before starting the next. No batching.
• Working-dir state — Debug audit state lives in .powernative/debug-app/: fixes.md, unresolved.md, injected-logs.md, health.json, and metro-cursor.json. Metro logs live in the already-ignored .powernative/metro-logs/. Both survive chat/editor restarts without binding state to a specific agent host.
• Defense-in-depth redaction — The Metro logger removes credential-like lines before writing .powernative, but /debug-app must independently minimize and sanitize every value before persisting it to .powernative/debug-app/. Never copy raw response bodies, record objects, tokens, headers, trace payloads, or absolute home-directory paths into debugger state.
• The port is the log identity — the dev-server port is the number the QR encodes, the device dials, and this skill verifies. Liveness is a socket probe (does the log's PID still hold that port?), never terminal scrollback. A port-taken status means the log belongs to a dead session and must not be diagnosed.
• Never fix history — the log is a record of the past, so an error in it is not proof of a current problem. Errors found in the baseline window must pass the Phase 0.2.1 supersession check before any code is edited. Editing working code to chase an already-resolved error is a worse outcome than reporting nothing.
• First-party native packages are an immutable boundary — a frame under node_modules/@microsoft/power-apps-native-* is evidence, not proof, of package ownership. First rule out invalid app inputs, unsupported configuration, and misuse of the package's documented API. Once the evidence confirms a defect inside an installed @microsoft/power-apps-native-* package, do not apply a customer-project workaround: do not edit node_modules/, create a patch-package patch or postinstall rewrite, vendor or fork package source, redirect the package through Metro/Babel/TypeScript aliases, or replace its dependency with a git, tarball, or local fork. Record a sanitized package-defect report and route the user to `/report-issue