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.

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

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

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).

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.

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:

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>.

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.

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 <file> / stop).

• On stop → BLOCKED: user stopped after diagnosis (nothing edited; diagnosis logged at Step 9).
• On investigate #2 → deepen that hypothesis, re-present.
• If no hypothesis reaches at least MEDIUM confidence after the trace → stop with NEEDS_CONTEXT: <what additional evidence is needed> (e.g. "please paste the raw <name>Json output" or "a host log line from the crash"). Never fabricate a fix for an unconfirmed cause.

Now derive the fix. First classify it the same way a careful edit does, because a fix can be more than a code patch:

Then present the code fix plan:

Fix plan:

<path/to/file>
  - Replace: <specific symbol / region> → <replacement> (rationale tied to the diagnosis)
  - Add:     <specific addition>

Contract impact: <"none" | "method set / receiver / nativeModule moves — ./manifest.json + PCF key updated in this same change, re-staged via /generate-ppmplugin-manifest">
Total: N files changed.
Apply? (yes / no / show me <file>)

Contract seam. If the fix changes the method set, the receiver/routing name, or the native-module name (Android getName() / iOS +moduleName = <Pascal>Module), three artifacts move together in this fix: native source, the committed ./manifest.json (receivers[] / methods, edited surgically), and the PCF composite key <name>/<receiver>. Then /generate-ppmplugin-manifest re-validates + re-stages the manifest. A pure-behavior fix that leaves those unchanged does not touch the manifest.

If the fix requires PCF edits but has_pcf: false, stop with BLOCKED: this fix requires PCF edits but pcf/ is not scaffolded — run /generate-pcf-companion first.

Gate: wait for explicit yes. On no → BLOCKED: user declined fix plan (diagnosis still logged). On show me <file> → print the proposed content and re-ask.

Apply the planned edits with the Edit tool. Rules:

• Surgical, not wholesale. Change the lines the diagnosis identified; don't rewrite the function or file. Reserve Write for a genuinely new file (rare in debug).
• Atomic per file. Apply all edits to one file in sequence; never leave a file half-edited.
• Atomic across files (best effort). If a multi-file batch fails mid-way, stop, report which files were written and which weren't, and tell the user to git diff / git checkout the half-written ones. Do NOT auto-revert (destructive, not on the safe list).
• No collateral edits. Only touch files on the plan. Note unrelated issues in the summary; don't fix them in this pass.

After applying, re-read every touched file and walk shared/self-critique-protocol.md. A fix that resolves the reported symptom can introduce a new one (fixing an Android crash by deferring init might leave a first-call race; correcting the composite key might orphan an output).

1. Re-read each edited file fresh from disk (not from memory).
2. Walk the gates — PRD coverage, user journey, layout, state, cross-platform parity, reversibility, lifecycle, spec-drift, plus the 3P Gates 10 (buildability / bundle-fit) and 11 (PCF↔native round-trip). Pay special attention to Gate 11 — most debug fixes touch the very round-trip that broke.
3. Report + apply fixes per the protocol's severity/autofix cadence: mechanical fixes in one batch (one yes); structural fixes each gated; judgment calls surfaced as concerns. Re-loop up to 3 iterations.

Return-status impact: all gates clean → continue. Blockers deferred → BLOCKED: self-critique blockers — <list> (fix stays applied; user re-runs after deciding). Concerns remain → continue with DONE_WITH_CONCERNS.

Verify the fix actually addresses the symptom, scoped to what was edited:

Validate before you interpolate. <Pascal> comes from PRD identity, not from a constant — a crafted or malformed value turns the command below into arbitrary shell or escapes the project directory. Before running it: require <Pascal> to match ^[A-Za-z][A-Za-z0-9]*$ (no separators, dots, or path segments), resolve pcf/<Pascal>PCF and confirm the real path stays inside pcf/, then pass it as a single quoted argument rather than splicing it into shell syntax. On failure, STOP with BLOCKED: refusing to run a build command with an invalid <Pascal> value — <value>.

The definitive verification for a field bug is a rebuild + on-device retest — a passing smoke check confirms the fix compiles, not that the symptom is gone. Say so explicitly in the summary. On smoke-check failure: report the failing command + the most relevant error line, do NOT auto-revert, stop with BLOCKED: smoke check failed — <one-line cause> (still log at Step 9).

1. Never fix without a located cause. Every fix traces to file:line evidence from Step 4/5. No confirmed cause → NEEDS_CONTEXT, not a speculative patch.
2. Two gates: diagnosis, then fix plan. Never edit code silently. On a case-A/C spec fix, the doc edit gets its own mini-gate first.
3. Never blow away unrelated files. Only files on the Step 6 plan are touched — no drive-by refactors.
4. Never auto-revert on failure. Surface it, stop; the user reviews git diff.
5. File-edit policy — three categories (identical to the generate/edit discipline):
   • Tool-managed — NEVER edit: .git/, lockfiles (pnpm-lock.yaml, package-lock.json, Podfile.lock), the generated bundle + its staging (ppmplugin/staging/manifest.json, ppmplugin/ outputs, any .ppmplugin), PCF generated artifacts (pcf/<Pascal>PCF/generated/), build outputs (lib/, dist/, build/, pcf/<Pascal>PCF/out/), *.bak.*, .claude/. (The committed ./manifest.json at repo root is the opposite — a consumer site you DO edit when the contract moves.)
   • Skill-managed — updated only via the canonical state step: .extension-state.md (this skill's Step 9). No mid-flow direct edits.
   • User-editable on request: .gitignore, CHANGELOG.md, LICENSE, README.md, PCF eslint.config.js / tsconfig.json, and all source (ios/**, android/**, pcf/<Pascal>PCF/{index.ts,ControlManifest.Input.xml}).
6. Atomic per file, best-effort across files.
7. Contract stays consistent. If a fix moves the method set / receiver / nativeModule, ./manifest.json + native + PCF move together, then re-stage via /generate-ppmplugin-manifest. Verify with /test-native-extension Layer 0.
8. Spec and code stay in sync. A case-A/C fix updates PRD/ARCHITECTURE first; a case-B fix logs the drift as such. Never silently update the spec to match a bug.
9. PCF is auto-detected, never assumed. No pcf/<Pascal>PCF/ControlManifest.Input.xml → don't write to pcf/; route to /generate-pcf-companion if the fix needs it.
10. Don't auto-chain; do honor an explicit pick at Step 9.2.
11. A smoke check is not an on-device confirmation. Always tell the user the fix must be rebuilt and retested on device to confirm the field symptom is gone.

End every run with one of:

• DONE — root cause located, fix applied, smoke check passed (or native-only with the rebuild+retest reminder printed).
• DONE_WITH_CONCERNS: <list> — fix applied but with caveats (self-critique concerns, missing expected files, an unconfirmed secondary hypothesis).
• BLOCKED: <reason> — user stopped/declined, smoke check failed, PRD missing, or PCF needed but absent.
• NEEDS_CONTEXT: <what's unclear> — symptom too thin, or no cause reached sufficient confidence.