---

name: debug-extension description: "Diagnose and fix failures in a built third-party .ppmplugin control: crashes, silent no-ops, PCF error outputs, or incorrect behavior. Uses the reported symptom, shared/error-codes.md, and file-level evidence to trace the manifest, Android/iOS modules, PCF dispatch, and build configuration. Produces a ranked diagnosis, asks for approval, then applies a surgical fix while keeping the committed manifest and affected contracts synchronized. Re-validates manifest changes through /generate-ppmplugin-manifest." allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill model: opus

/debug-extension

Investigate a failure the user observed while testing a built .ppmplugin control, find the root cause, and fix it. The wrap binary runs inside the customer's shell with no logcat / Xcode console / native debugger reachable, so the evidence is usually just the PCF's ErrorCode / ErrorMessage, the raw <name>Json diagnostic output, a host log line, or the user's description of what they saw. This skill turns that thin evidence into a located root cause and a fix.

Investigation-first, fix as the resolution. Unlike a plain "apply this change" flow, /debug-extension starts from a symptom and works backward to a cause before touching code. When the cause is found, it proposes the fix and applies it under the same discipline a careful edit uses (spec-vs-drift diagnosis, contract-consistency, surgical edits, gates).

This is one door, not the only door. Per shared/shared-instructions.md §7.5, a fix can be applied from any skill or a plain conversational turn — the user is never blocked or forced to route through this skill. What this skill adds is structure for a reported problem: the symptom→layer triage, the dispatch-path trace, and the located-evidence diagnosis before any edit. Reach for it when something broke on device and you don't yet know why; for a planned feature change where you already know what to edit, just edit directly.

When to use:

• "I tapped the button and nothing happened — no error, no UI." (silent no-op)
• "The PCF shows ErrorCode: PARSE / ErrorMessage: ...." (a code to trace)
• "The app crashes the moment the screen loads." (crash-at-launch)
• "Host log says Loaded 0 plugin package(s)." (a native-load signature)
• "It works on iOS but does nothing on Android." (parity / transport bug)
• "The Done button returns the wrong data." (behavior drift)

When NOT to use:

• No repo yet → /generate-native-extension.
• A brand-new operation → /design-native-extension-feature, then generate.
• A planned change with a known edit and no reported failure → just edit (any skill / chat).
• A build that never produced a binary → the failure is a build failure; run /generate-ppmplugin and read its stage output first.

Decoupled from generate-*. This skill refuses to run if no extension repo is detected. It does NOT scaffold, install dependencies, build binaries, or assemble the bundle. It diagnoses, then edits files.

---

Step 0 — Verify this is an extension repo

Detect the repo in this order. Stop with BLOCKED: not an extension repo (no <X> found) if any required signal is missing.

| Signal | Required? | Check | |---|---|---| | PRD.md exists at repo root | Yes | The spec is the baseline the observed behavior is compared against. | | package.json exists at repo root | Yes | Confirms this is a generated extension repo, not a random directory. | | ARCHITECTURE.md exists at repo root | No | Strongly preferred — holds the dispatch contract + per-op impl the trace follows. Note its absence as a concern. | | .extension-state.md exists at repo root | No | Informational — prior edits / drift entries are debugging leads. Created at Step 9 if absent. | | pcf/ folder with a ControlManifest.Input.xml inside | No | Drives PCF detection. Use Glob under pcf/ to locate the manifest and capture has_pcf: true|false. | | ppmplugin/ build output / a .ppmplugin artifact | No | Informational — confirms a binary was built (this skill debugs built controls). Absence → the failure may be pre-build; note it. |

If PRD or package.json is missing, suggest /generate-native-extension and stop.

---

Step 1 — Read shared docs, PRD, ARCHITECTURE, manifest, and state

In this order:

1. shared/shared-instructions.md — constants, return-status codes (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT), safety rules.
2. shared/error-codes.md — the canonical catalog + the symptom → likely cause → where-to-look map. This is the core input to triage (Step 3). Read it fully.
3. shared/naming-conventions.md — maps PRD identity to file paths for the trace.
4. shared/repo-layout.md — the expected file tree.
5. shared/ppmplugin-format.md — the dispatch contract, the wrap sendAsync transport, the { isUpdate, message } response container, and the native-load model (§2, §5, §5b). Essential for tracing transport / load failures.
6. ./PRD.md — full read (identity, operations, expected behavior).
7. ./ARCHITECTURE.md — full read (SDK pin, per-op impl walkthroughs, message contract, §5 error codes, manifest impl). The trace follows this.
8. ./manifest.json — the committed dispatch contract (name, receivers[].method, receivers[].nativeModule).
9. ./.extension-state.md — prior ## Edits / ## Debug entries and any recorded drift — often the fastest lead.

Skip shared/prereq-check.md. Debug installs/auths nothing. If a fix later needs the PCF npm run build, Step 8 surfaces a missing toolchain then.

Per shared-instructions.md §9.2, print a one-line prereq notice at the start of Step 1:

Prereq check — /debug-extension: skipped (skill does no installs / auth / network — investigation only until a fix's smoke check).

---

Step 2 — Capture the bug report

Gather the symptom. If the user invoked the skill with no detail, prompt for it — ask for whichever of these they have (one consolidated prompt, not five):

• What happened vs. what they expected (the observable behavior).
• ErrorCode / ErrorMessage shown on the PCF (or in Power Fx via Self.ErrorCode / Self.ErrorMessage).
• The raw <name>Json diagnostic output (the wire bytes — transport-level forensics).
• Any host log line (e.g. Loaded 0 plugin package(s), native module '<x>' not loaded, method '<m>' not found, a stack trace).
• Platform (iOS / Android / both) and when it happens (at launch / on tap / after the operation).
• Repro steps, if any.

Keep the raw report in working context for the trace — do not paraphrase away detail, since an exact code or message is the highest-signal input. Do not persist it verbatim. .extension-state.md is committed to the repo, and a pasted report routinely carries a raw response, stack trace, host log lines, file paths, URLs, tokens, or customer data. Step 9 writes a redacted one-line summary instead — see the redaction rule there.

---

Step 3 — Triage: map the symptom to candidate layers

Using shared/error-codes.md (§2 module codes, §3 transport codes, §4 no-code signatures), classify the symptom into one or more candidate layers, most-likely first:

| Layer | Reached when the symptom looks like… | |---|---| | PCF / transport (pcf/<Pascal>PCF/index.ts) | PARSE, UNEXPECTED_PAYLOAD, BRIDGE_FAILED, NOT_IN_WRAP; silent no-op on tap; every call fails identically. | | Dispatch contract (./manifest.json ↔ native names ↔ PCF key) | method '<m>' not found, native module '<x>' not loaded, BRIDGE_FAILED with a routing message; works on one platform only. | | Native module — Android (android/.../<Pascal>Module.kt) | INTERNAL_ERROR / PERMISSION_DENIED / NO_ACTIVITY on Android; Android-only crash; Loaded 0 plugin package(s). | | Native module — iOS (ios/RCT<Pascal>Module.m) | INTERNAL_ERROR / PERMISSION_DENIED on iOS; iOS-only crash / no-op; +moduleName / requiresMainQueueSetup load issue. | | Native load / lifecycle (constructor, package class) | Crash at launch before any UI; module never loads. | | Build config / RN pin (package.json, android/build.gradle, .podspec) | React header / undefined-symbol errors; behavior tied to an SDK level; a pin divergence from the host RN. | | Behavior / spec (native op body vs PRD/ARCHITECTURE) | Wrong result, missing control, incorrect payload — no error code, just wrong output. |

A single report can span layers (e.g. UNEXPECTED_PAYLOAD is usually PCF, but can be a non-conforming native response). List every plausible layer; Step 4 confirms/eliminates.

If the report is too thin to triage, ask one targeted clarifying question (e.g. "Does it fail on both platforms or just one?"). If still unclear, stop with NEEDS_CONTEXT: <what's unclear>.

---

Step 4 — Investigate: trace the path and gather evidence

For each candidate layer, read the implicated files and confirm or eliminate the hypothesis with concrete evidence. Do NOT guess — open the file and cite the line.

Convention-derived files (substitute <Pascal> / <lower> from PRD identity via shared/naming-conventions.md):

• PCF / transport → pcf/<Pascal>PCF/index.ts (invokeBridge, extractResponse, onTrigger outcome branch, args: [request], the composite key), pcf/<Pascal>PCF/ControlManifest.Input.xml.
• Dispatch contract → ./manifest.json receivers[]; native getName() (Android) / +moduleName (iOS); the PCF composite key <name>/<receiver> + method. Cross-check all three agree.
• Native Android → android/src/main/java/com/powerapps/<lower>/<Pascal>Module.kt (+ <Pascal>CaptureActivity.kt), the ReactPackage class (public no-arg constructor), android/src/main/AndroidManifest.xml.
• Native iOS → ios/RCT<Pascal>Module.{h,m} (+moduleName, +requiresMainQueueSetup, no-arg init), the presented VC.
• Build / pin → package.json (RN pin 0.79.7), android/build.gradle, ios/<Pascal>Extension.podspec.

Trace techniques:

• Follow the dispatch path end-to-end: PCF key → sendAsync envelope ({ method, args: [request] }) → manifest receivers[] → native method → response JSON → extractResponse → PCF output. A break anywhere is the bug.
• Grep for the specific symbol in the report (an error code, a field name, a method name) across ios/, android/, pcf/ to find every site that emits or consumes it.
• Compare iOS vs Android when the symptom is platform-specific — the delta is the lead.
• Check the raw <name>Json against the { status, result?/error?, message? } convention and the wrap { isUpdate, message } container — a shape mismatch points to extractResponse vs a bare parse.
• **Match against error-codes.md §4 signatures**: Loaded 0 plugin package(s)→ Android package no-arg ctor;cordova.exec` in the PCF → forbidden (silent no-op); React header errors → RN pin divergence.

Read shared/self-critique-protocol.md if the trace touches a per-operation impl — its gates (state coverage, cross-platform parity, lifecycle) sharpen the hypotheses.

---

Step 5 — Root-cause diagnosis + gate

Present a ranked diagnosis. Each hypothesis is anchored in evidence, not intuition:

Diagnosis for: "<verbatim symptom>"

1. [HIGH confidence] <one-line root cause>
   Evidence: <file>:<line> — <what the code does / doesn't do>
   Why it produces this symptom: <one sentence tied to error-codes.md>
   Layer: PCF | dispatch contract | native-android | native-ios | native-load | build/pin | behavior

2. [MEDIUM confidence] <alternative cause>
   Evidence: ...

Ruled out: <hypothesis> — <why the evidence eliminates it>

Recommended fix (for #1): <what would change, in which file(s)>

Gate: `Proceed with the fix for #1? (yes / investigate #2 instead / show me <