[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699QFVT6NG0MTFMXGSHGWQ4":3,"skill-same:01M699QFVT6NG0MTFMXGSHGWQ4":75},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":45,"linkOnly":46,"markdownContent":47,"markdownBody":48,"frontMatter":49,"refName":51,"commitSha":52,"skillDirectory":53,"forksCount":54,"repositoryHtmlUrl":55,"repositoryHomepageUrl":56,"ownerHtmlUrl":57,"ownerBlogUrl":58,"ownerDescription":59,"updatedAt":60,"install":61,"resources":74},"01M699QFVT6NG0MTFMXGSHGWQ4","debug-extension",null,"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\u002Ferror-codes.md`, and file-level evidence to trace the manifest, Android\u002FiOS 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 \u002Fgenerate-ppmplugin-manifest.","microsoft\u002Fpower-platform-skills","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699JVYJFB75D9JM70BN4H0Q",1149,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fpower-apps-mobile-extension\u002Fskills\u002Fdebug-extension\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44],"debug extension","debug","extension","fix","surgical","outputs","for","affected","opus","re","diagnosis","shared","modules","android","edit","write","read","manifest","file","generate","pcf","2026-11-10 10:12:30",false,"---\nname: debug-extension\ndescription: \"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\u002Ferror-codes.md`, and file-level evidence to trace the manifest, Android\u002FiOS 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 \u002Fgenerate-ppmplugin-manifest.\"\nallowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill\nmodel: opus\n---\n\n# \u002Fdebug-extension\n\nInvestigate a failure the user observed while testing a **built** `.ppmplugin` control,\nfind the root cause, and fix it. The wrap binary runs inside the customer's shell with\n**no logcat \u002F Xcode console \u002F native debugger reachable**, so the evidence is usually just\nthe PCF's `ErrorCode` \u002F `ErrorMessage`, the raw `\u003Cname>Json` diagnostic output, a host log\nline, or the user's description of what they saw. This skill turns that thin evidence into\na located root cause and a fix.\n\n**Investigation-first, fix as the resolution.** Unlike a plain \"apply this change\" flow,\n`\u002Fdebug-extension` starts from a *symptom* and works backward to a *cause* before touching\ncode. When the cause is found, it proposes the fix and applies it under the same discipline\na careful edit uses (spec-vs-drift diagnosis, contract-consistency, surgical edits, gates).\n\n**This is one door, not the only door.** Per `shared\u002Fshared-instructions.md §7.5`, a fix\ncan be applied from *any* skill or a plain conversational turn — the user is never blocked\nor forced to route through this skill. What this skill adds is *structure* for a reported\nproblem: the symptom→layer triage, the dispatch-path trace, and the located-evidence\ndiagnosis before any edit. Reach for it when something *broke on device* and you don't yet\nknow why; for a planned feature change where you already know what to edit, just edit\ndirectly.\n\n**When to use:**\n- \"I tapped the button and nothing happened — no error, no UI.\" (silent no-op)\n- \"The PCF shows `ErrorCode: PARSE` \u002F `ErrorMessage: ...`.\" (a code to trace)\n- \"The app crashes the moment the screen loads.\" (crash-at-launch)\n- \"Host log says `Loaded 0 plugin package(s)`.\" (a native-load signature)\n- \"It works on iOS but does nothing on Android.\" (parity \u002F transport bug)\n- \"The Done button returns the wrong data.\" (behavior drift)\n\n**When NOT to use:**\n- No repo yet → `\u002Fgenerate-native-extension`.\n- A brand-new operation → `\u002Fdesign-native-extension-feature`, then generate.\n- A planned change with a known edit and no reported failure → just edit (any skill \u002F chat).\n- A build that never produced a binary → the failure is a *build* failure; run\n  `\u002Fgenerate-ppmplugin` and read its stage output first.\n\n**Decoupled from generate-*.** This skill refuses to run if no extension repo is detected.\nIt does NOT scaffold, install dependencies, build binaries, or assemble the bundle. It\ndiagnoses, then edits files.\n\n---\n\n## Step 0 — Verify this is an extension repo\n\nDetect the repo in this order. Stop with `BLOCKED: not an extension repo (no \u003CX> found)`\nif any **required** signal is missing.\n\n| Signal | Required? | Check |\n|---|---|---|\n| `PRD.md` exists at repo root | **Yes** | The spec is the baseline the observed behavior is compared against. |\n| `package.json` exists at repo root | **Yes** | Confirms this is a generated extension repo, not a random directory. |\n| `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. |\n| `.extension-state.md` exists at repo root | No | Informational — prior edits \u002F drift entries are debugging leads. Created at Step 9 if absent. |\n| `pcf\u002F` folder with a `ControlManifest.Input.xml` inside | No | Drives PCF detection. Use Glob under `pcf\u002F` to locate the manifest and capture `has_pcf: true|false`. |\n| `ppmplugin\u002F` build output \u002F a `.ppmplugin` artifact | No | Informational — confirms a binary was built (this skill debugs *built* controls). Absence → the failure may be pre-build; note it. |\n\nIf PRD or `package.json` is missing, suggest `\u002Fgenerate-native-extension` and stop.\n\n---\n\n## Step 1 — Read shared docs, PRD, ARCHITECTURE, manifest, and state\n\nIn this order:\n\n1. `shared\u002Fshared-instructions.md` — constants, return-status codes (`DONE` \u002F `DONE_WITH_CONCERNS` \u002F `BLOCKED` \u002F `NEEDS_CONTEXT`), safety rules.\n2. **`shared\u002Ferror-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.\n3. `shared\u002Fnaming-conventions.md` — maps PRD identity to file paths for the trace.\n4. `shared\u002Frepo-layout.md` — the expected file tree.\n5. `shared\u002Fppmplugin-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 \u002F load failures.\n6. `.\u002FPRD.md` — full read (identity, operations, expected behavior).\n7. `.\u002FARCHITECTURE.md` — full read (SDK pin, per-op impl walkthroughs, message contract, §5 error codes, manifest impl). The trace follows this.\n8. `.\u002Fmanifest.json` — the committed dispatch contract (`name`, `receivers[].method`, `receivers[].nativeModule`).\n9. `.\u002F.extension-state.md` — prior `## Edits` \u002F `## Debug` entries and any recorded drift — often the fastest lead.\n\n**Skip `shared\u002Fprereq-check.md`.** Debug installs\u002Fauths nothing. If a fix later needs the\nPCF `npm run build`, Step 8 surfaces a missing toolchain then.\n\nPer `shared-instructions.md §9.2`, print a one-line prereq notice at the start of Step 1:\n\n```\nPrereq check — \u002Fdebug-extension: skipped (skill does no installs \u002F auth \u002F network — investigation only until a fix's smoke check).\n```\n\n---\n\n## Step 2 — Capture the bug report\n\nGather the symptom. If the user invoked the skill with no detail, prompt for it — ask for\nwhichever of these they have (one consolidated prompt, not five):\n\n- **What happened vs. what they expected** (the observable behavior).\n- **`ErrorCode` \u002F `ErrorMessage`** shown on the PCF (or in Power Fx via `Self.ErrorCode` \u002F `Self.ErrorMessage`).\n- **The raw `\u003Cname>Json`** diagnostic output (the wire bytes — transport-level forensics).\n- **Any host log line** (e.g. `Loaded 0 plugin package(s)`, `native module '\u003Cx>' not loaded`, `method '\u003Cm>' not found`, a stack trace).\n- **Platform** (iOS \u002F Android \u002F both) and **when** it happens (at launch \u002F on tap \u002F after the operation).\n- **Repro steps**, if any.\n\nKeep the raw report in working context for the trace — do not paraphrase away detail, since\nan exact code or message is the highest-signal input. **Do not persist it verbatim.**\n`.extension-state.md` is committed to the repo, and a pasted report routinely carries a raw\nresponse, stack trace, host log lines, file paths, URLs, tokens, or customer data. Step 9\nwrites a redacted one-line summary instead — see the redaction rule there.\n\n---\n\n## Step 3 — Triage: map the symptom to candidate layers\n\nUsing **`shared\u002Ferror-codes.md`** (§2 module codes, §3 transport codes, §4 no-code\nsignatures), classify the symptom into one or more **candidate layers**, most-likely first:\n\n| Layer | Reached when the symptom looks like… |\n|---|---|\n| **PCF \u002F transport** (`pcf\u002F\u003CPascal>PCF\u002Findex.ts`) | `PARSE`, `UNEXPECTED_PAYLOAD`, `BRIDGE_FAILED`, `NOT_IN_WRAP`; silent no-op on tap; every call fails identically. |\n| **Dispatch contract** (`.\u002Fmanifest.json` ↔ native names ↔ PCF key) | `method '\u003Cm>' not found`, `native module '\u003Cx>' not loaded`, `BRIDGE_FAILED` with a routing message; works on one platform only. |\n| **Native module — Android** (`android\u002F...\u002F\u003CPascal>Module.kt`) | `INTERNAL_ERROR` \u002F `PERMISSION_DENIED` \u002F `NO_ACTIVITY` on Android; Android-only crash; `Loaded 0 plugin package(s)`. |\n| **Native module — iOS** (`ios\u002FRCT\u003CPascal>Module.m`) | `INTERNAL_ERROR` \u002F `PERMISSION_DENIED` on iOS; iOS-only crash \u002F no-op; `+moduleName` \u002F `requiresMainQueueSetup` load issue. |\n| **Native load \u002F lifecycle** (constructor, package class) | Crash **at launch** before any UI; module never loads. |\n| **Build config \u002F RN pin** (`package.json`, `android\u002Fbuild.gradle`, `.podspec`) | React header \u002F undefined-symbol errors; behavior tied to an SDK level; a pin divergence from the host RN. |\n| **Behavior \u002F spec** (native op body vs PRD\u002FARCHITECTURE) | Wrong result, missing control, incorrect payload — no error code, just wrong output. |\n\nA single report can span layers (e.g. `UNEXPECTED_PAYLOAD` is *usually* PCF, but *can* be a\nnon-conforming native response). List every plausible layer; Step 4 confirms\u002Feliminates.\n\nIf the report is too thin to triage, ask **one** targeted clarifying question (e.g. \"Does\nit fail on both platforms or just one?\"). If still unclear, stop with\n`NEEDS_CONTEXT: \u003Cwhat's unclear>`.\n\n---\n\n## Step 4 — Investigate: trace the path and gather evidence\n\nFor each candidate layer, read the implicated files and confirm or eliminate the hypothesis\nwith concrete evidence. Do NOT guess — open the file and cite the line.\n\nConvention-derived files (substitute `\u003CPascal>` \u002F `\u003Clower>` from PRD identity via\n[`shared\u002Fnaming-conventions.md`](..\u002F..\u002Fshared\u002Fnaming-conventions.md)):\n\n- **PCF \u002F transport** → `pcf\u002F\u003CPascal>PCF\u002Findex.ts` (`invokeBridge`, `extractResponse`, `onTrigger` outcome branch, `args: [request]`, the composite key), `pcf\u002F\u003CPascal>PCF\u002FControlManifest.Input.xml`.\n- **Dispatch contract** → `.\u002Fmanifest.json` `receivers[]`; native `getName()` (Android) \u002F `+moduleName` (iOS); the PCF composite key `\u003Cname>\u002F\u003Creceiver>` + `method`. Cross-check all three agree.\n- **Native Android** → `android\u002Fsrc\u002Fmain\u002Fjava\u002Fcom\u002Fpowerapps\u002F\u003Clower>\u002F\u003CPascal>Module.kt` (+ `\u003CPascal>CaptureActivity.kt`), the `ReactPackage` class (public no-arg constructor), `android\u002Fsrc\u002Fmain\u002FAndroidManifest.xml`.\n- **Native iOS** → `ios\u002FRCT\u003CPascal>Module.{h,m}` (`+moduleName`, `+requiresMainQueueSetup`, no-arg init), the presented VC.\n- **Build \u002F pin** → `package.json` (RN pin `0.79.7`), `android\u002Fbuild.gradle`, `ios\u002F\u003CPascal>Extension.podspec`.\n\nTrace techniques:\n- **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.\n- **Grep for the specific symbol** in the report (an error code, a field name, a method name) across `ios\u002F`, `android\u002F`, `pcf\u002F` to find every site that emits or consumes it.\n- **Compare iOS vs Android** when the symptom is platform-specific — the delta is the lead.\n- **Check the raw `\u003Cname>Json`** against the `{ status, result?\u002Ferror?, message? }` convention and the wrap `{ isUpdate, message }` container — a shape mismatch points to `extractResponse` vs a bare parse.\n- **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.\n\nRead `shared\u002Fself-critique-protocol.md` if the trace touches a per-operation impl — its\ngates (state coverage, cross-platform parity, lifecycle) sharpen the hypotheses.\n\n---\n\n## Step 5 — Root-cause diagnosis + gate\n\nPresent a ranked diagnosis. Each hypothesis is anchored in evidence, not intuition:\n\n```\nDiagnosis for: \"\u003Cverbatim symptom>\"\n\n1. [HIGH confidence] \u003Cone-line root cause>\n   Evidence: \u003Cfile>:\u003Cline> — \u003Cwhat the code does \u002F doesn't do>\n   Why it produces this symptom: \u003Cone sentence tied to error-codes.md>\n   Layer: PCF | dispatch contract | native-android | native-ios | native-load | build\u002Fpin | behavior\n\n2. [MEDIUM confidence] \u003Calternative cause>\n   Evidence: ...\n\nRuled out: \u003Chypothesis> — \u003Cwhy the evidence eliminates it>\n\nRecommended fix (for #1): \u003Cwhat would change, in which file(s)>\n```\n\n**Gate**: `Proceed with the fix for #1? (yes \u002F investigate #2 instead \u002F show me \u003Cfile> \u002F stop)`.\n\n- On `stop` → `BLOCKED: user stopped after diagnosis` (nothing edited; diagnosis logged at Step 9).\n- On `investigate #2` → deepen that hypothesis, re-present.\n- If **no** hypothesis reaches at least MEDIUM confidence after the trace → stop with\n  `NEEDS_CONTEXT: \u003Cwhat additional evidence is needed>` (e.g. \"please paste the raw\n  `\u003Cname>Json` output\" or \"a host log line from the crash\"). Never fabricate a fix for an\n  unconfirmed cause.\n\n---\n\n## Step 6 — Fix plan + spec-vs-drift check + gate\n\nNow derive the fix. First classify it the same way a careful edit does, because a fix can\nbe more than a code patch:\n\n| Case | What the fix is | Action |\n|---|---|---|\n| **B — code drift** (most common) | The code diverged from a spec that is already correct (e.g. a missing `extractResponse`, a wrong composite key, a swallowed exception). | Fix the code only. Print `\u003Cdoc> §\u003Cn> already specifies the correct behavior — fixing code only.` |\n| **A — spec wrong** | The observed behavior is actually what PRD\u002FARCHITECTURE currently says, but that spec is wrong. | Propose the PRD\u002FARCHITECTURE edit **first** (its own mini-gate), apply it, then derive the code. |\n| **C — both** | Spec is ambiguous\u002Fpartial and code is partial. | Update the doc detail, then fix the code. |\n\nThen present the code fix plan:\n\n```\nFix plan:\n\n\u003Cpath\u002Fto\u002Ffile>\n  - Replace: \u003Cspecific symbol \u002F region> → \u003Creplacement> (rationale tied to the diagnosis)\n  - Add:     \u003Cspecific addition>\n\nContract impact: \u003C\"none\" | \"method set \u002F receiver \u002F nativeModule moves — .\u002Fmanifest.json + PCF key updated in this same change, re-staged via \u002Fgenerate-ppmplugin-manifest\">\nTotal: N files changed.\nApply? (yes \u002F no \u002F show me \u003Cfile>)\n```\n\n**Contract seam.** If the fix changes the method set, the receiver\u002Frouting name, or the\nnative-module name (Android `getName()` \u002F iOS `+moduleName` = `\u003CPascal>Module`), three\nartifacts move **together** in this fix: native source, the committed `.\u002Fmanifest.json`\n(`receivers[]` \u002F `methods`, edited surgically), and the PCF composite key `\u003Cname>\u002F\u003Creceiver>`.\nThen `\u002Fgenerate-ppmplugin-manifest` re-validates + re-stages the manifest. A pure-behavior\nfix that leaves those unchanged does not touch the manifest.\n\nIf the fix requires PCF edits but `has_pcf: false`, stop with `BLOCKED: this fix requires\nPCF edits but pcf\u002F is not scaffolded — run \u002Fgenerate-pcf-companion first`.\n\n**Gate**: wait for explicit `yes`. On `no` → `BLOCKED: user declined fix plan` (diagnosis\nstill logged). On `show me \u003Cfile>` → print the proposed content and re-ask.\n\n---\n\n## Step 7 — Apply the fix\n\nApply the planned edits with the `Edit` tool. Rules:\n\n- **Surgical, not wholesale.** Change the lines the diagnosis identified; don't rewrite the\n  function or file. Reserve `Write` for a genuinely new file (rare in debug).\n- **Atomic per file.** Apply all edits to one file in sequence; never leave a file\n  half-edited.\n- **Atomic across files (best effort).** If a multi-file batch fails mid-way, stop, report\n  which files were written and which weren't, and tell the user to `git diff` \u002F `git\n  checkout` the half-written ones. Do NOT auto-revert (destructive, not on the safe list).\n- **No collateral edits.** Only touch files on the plan. Note unrelated issues in the\n  summary; don't fix them in this pass.\n\n---\n\n## Step 7.5 — Self-critique against the proactive protocol\n\nAfter applying, re-read every touched file and walk\n[`shared\u002Fself-critique-protocol.md`](..\u002F..\u002Fshared\u002Fself-critique-protocol.md). A fix that\nresolves the reported symptom can introduce a new one (fixing an Android crash by deferring\ninit might leave a first-call race; correcting the composite key might orphan an output).\n\n1. **Re-read** each edited file fresh from disk (not from memory).\n2. **Walk the gates** — PRD coverage, user journey, layout, state, cross-platform parity,\n   reversibility, lifecycle, spec-drift, plus the 3P Gates 10 (buildability \u002F bundle-fit)\n   and 11 (PCF↔native round-trip). Pay special attention to **Gate 11** — most debug fixes\n   touch the very round-trip that broke.\n3. **Report + apply fixes** per the protocol's severity\u002Fautofix cadence: mechanical fixes in\n   one batch (one `yes`); structural fixes each gated; judgment calls surfaced as concerns.\n   Re-loop up to 3 iterations.\n\nReturn-status impact: all gates clean → continue. Blockers deferred → `BLOCKED:\nself-critique blockers — \u003Clist>` (fix stays applied; user re-runs after deciding).\nConcerns remain → continue with `DONE_WITH_CONCERNS`.\n\n---\n\n## Step 8 — Verify the fix\n\nVerify the fix actually addresses the symptom, scoped to what was edited:\n\n**Validate before you interpolate.** `\u003CPascal>` comes from PRD identity, not from a constant —\na crafted or malformed value turns the command below into arbitrary shell or escapes the\nproject directory. Before running it: require `\u003CPascal>` to match `^[A-Za-z][A-Za-z0-9]*$`\n(no separators, dots, or path segments), resolve `pcf\u002F\u003CPascal>PCF` and confirm the real path\nstays inside `pcf\u002F`, then pass it as a single quoted argument rather than splicing it into\nshell syntax. On failure, STOP with `BLOCKED: refusing to run a build command with an invalid\n\u003CPascal> value — \u003Cvalue>`.\n\n| Files edited | Verification | Why |\n|---|---|---|\n| Any `pcf\u002F\u003CPascal>PCF\u002F` `.ts` \u002F `ControlManifest.Input.xml` | `npm run build --prefix \"$PCF_DIR\"` | The only TS build in the repo — catches type + manifest errors immediately. |\n| Only `.kt` \u002F `.m` \u002F XML | Print: `Native files fixed — compile + on-device validation defer to \u002Fbuild-android-binary \u002F\u002F \u002Fbuild-ios-binary (via \u002Fgenerate-ppmplugin) and \u002Ftest-native-extension Layer 5. Rebuild + retest on device to confirm the symptom is gone.` | Native standalone compile isn't reliable here; the build skills do the real compile. |\n| Contract moved (`.\u002Fmanifest.json` \u002F names) | Re-run `\u002Fgenerate-ppmplugin-manifest` (re-validate + re-stage), then note that `\u002Fgenerate-ppmplugin` (rebuild + `\u002Faudit-ppmplugin`) is needed. | The staged manifest and the binary must be regenerated for the fix to reach the device. |\n\n**The definitive verification for a field bug is a rebuild + on-device retest** — a passing\nsmoke check confirms the fix compiles, not that the symptom is gone. Say so explicitly in\nthe summary. On smoke-check failure: report the failing command + the most relevant error\nline, do NOT auto-revert, stop with `BLOCKED: smoke check failed — \u003Cone-line cause>` (still\nlog at Step 9).\n\n---\n\n## Step 9 — State log + summary\n\n### 9.1 Update `.extension-state.md`\n\nAppend (don't overwrite) to a `## Debug` section (create it if absent):\n\n```markdown\n## Debug\n\n- \u003CISO timestamp> — \u003Cone-line summary of the bug + fix>\n  - Symptom: \"\u003Credacted one-line summary — see the redaction rule below>\"\n  - Root cause: \u003Clocated cause> (\u003Cfile>:\u003Cline>)\n  - Diagnosis case: A | B | C\n  - Docs changed: \u003Csections, or \"none\">\n  - Code changed: \u003Cfile paths>\n  - Contract moved: \u003C\"none\" | \"receiver\u002Fmethod\u002FnativeModule changed — .\u002Fmanifest.json updated; re-staged via \u002Fgenerate-ppmplugin-manifest\">\n  - Verification: \u003CPCF npm run build → PASS | native — rebuild + device retest required | etc.>\n  - Status: DONE | DONE_WITH_CONCERNS: \u003Creasons> | BLOCKED — \u003Creason>\n```\n\n**Redact before writing.** `.extension-state.md` is committed to the repo, so treat every\nfield as published. The `Symptom` line is a short paraphrase — the error code, the affected\noperation, and the observable behaviour — never the pasted report. Strip, from every field:\nsecrets and tokens; PII and customer data; request\u002Fresponse payloads and their fragments;\nabsolute or internal filesystem paths; internal URLs and hostnames; and stack traces beyond\nthe single frame that locates the cause. Keep `Root cause` to the repo-relative `\u003Cfile>:\u003Cline>`\nthat already lives in source control. If a detail is needed to justify the fix but can't be\nredacted safely, leave it out of the file and keep it in the chat.\n\n### 9.2 Final summary + next step\n\nOne paragraph: the located root cause, what was fixed, and the verification outcome — and\n**state plainly that an on-device retest (after a rebuild) is what confirms the symptom is\nresolved**. Then offer the next step via `AskUserQuestion` (shared-instructions §9.1),\npicking the options that fit the fix:\n\n- **Run \u002Fgenerate-ppmplugin** — rebuild the `.ppmplugin` + re-audit (re-validates + re-stages `.\u002Fmanifest.json` first). The recommended next step for a native or contract fix.\n- **Run \u002Ftest-native-extension** — re-validate the contract (Layer 0 cross-check; Layer 4 PCF compile). Good for a PCF or contract fix before the full rebuild.\n- **Run \u002Fgenerate-pcf-companion** — only if the fix needs PCF edits but `pcf\u002F` isn't scaffolded.\n- **Stay — I'll retest on device first.**\n\nPer the **Execute, don't describe** HARD RULE (§9.1), when the user picks a `Run \u002F…` option,\ninvoke that skill via the `Skill` tool in the same turn. Don't *auto*-chain on your own.\n\n---\n\n## Hard rules\n\n1. **Never fix without a located cause.** Every fix traces to file:line evidence from\n   Step 4\u002F5. No confirmed cause → `NEEDS_CONTEXT`, not a speculative patch.\n2. **Two gates: diagnosis, then fix plan.** Never edit code silently. On a case-A\u002FC spec\n   fix, the doc edit gets its own mini-gate first.\n3. **Never blow away unrelated files.** Only files on the Step 6 plan are touched — no\n   drive-by refactors.\n4. **Never auto-revert on failure.** Surface it, stop; the user reviews `git diff`.\n5. **File-edit policy — three categories** (identical to the generate\u002Fedit discipline):\n   - **Tool-managed — NEVER edit:** `.git\u002F`, lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `Podfile.lock`), the generated bundle + its staging (`ppmplugin\u002Fstaging\u002Fmanifest.json`, `ppmplugin\u002F` outputs, any `.ppmplugin`), PCF generated artifacts (`pcf\u002F\u003CPascal>PCF\u002Fgenerated\u002F`), build outputs (`lib\u002F`, `dist\u002F`, `build\u002F`, `pcf\u002F\u003CPascal>PCF\u002Fout\u002F`), `*.bak.*`, `.claude\u002F`. (The committed `.\u002Fmanifest.json` at repo root is the opposite — a consumer site you DO edit when the contract moves.)\n   - **Skill-managed — updated only via the canonical state step:** `.extension-state.md` (this skill's Step 9). No mid-flow direct edits.\n   - **User-editable on request:** `.gitignore`, `CHANGELOG.md`, `LICENSE`, `README.md`, PCF `eslint.config.js` \u002F `tsconfig.json`, and all source (`ios\u002F**`, `android\u002F**`, `pcf\u002F\u003CPascal>PCF\u002F{index.ts,ControlManifest.Input.xml}`).\n6. **Atomic per file, best-effort across files.**\n7. **Contract stays consistent.** If a fix moves the method set \u002F receiver \u002F nativeModule,\n   `.\u002Fmanifest.json` + native + PCF move together, then re-stage via\n   `\u002Fgenerate-ppmplugin-manifest`. Verify with `\u002Ftest-native-extension` Layer 0.\n8. **Spec and code stay in sync.** A case-A\u002FC fix updates PRD\u002FARCHITECTURE first; a case-B\n   fix logs the drift as such. Never silently update the spec to match a bug.\n9. **PCF is auto-detected, never assumed.** No `pcf\u002F\u003CPascal>PCF\u002FControlManifest.Input.xml`\n   → don't write to `pcf\u002F`; route to `\u002Fgenerate-pcf-companion` if the fix needs it.\n10. **Don't *auto*-chain; do honor an explicit pick** at Step 9.2.\n11. **A smoke check is not an on-device confirmation.** Always tell the user the fix must be\n    rebuilt and retested on device to confirm the field symptom is gone.\n\n---\n\n## Scenarios — how the flow plays out\n\n### Scenario 1 — Silent no-op on Android (PCF transport bug)\n\n```\nStep 2: Symptom = \"tap does nothing, no error, only on Android.\"\nStep 3: Triage → PCF\u002Ftransport (error-codes.md §4 top row) + dispatch contract.\nStep 4: Read pcf\u002F...\u002Findex.ts — invokeBridge calls cordova.exec directly, no sendAsync.\n        Evidence: index.ts:NN. Matches the §4 signature (cordova undefined in PCF sandbox).\nStep 5: [HIGH] cordova.exec used instead of the host-injected sendAsync → silent no-op,\n        worst on Android. Gate: proceed.\nStep 6: Case B (ppmplugin-format §2 already specifies sendAsync). Fix plan: replace\n        cordova.exec with window.PowerApps.NativeExtension.sendAsync + args:[request].\nStep 7: Apply. 7.5: self-critique Gate 11 (round-trip) clean.\nStep 8: cd pcf && npm run build → PASS. Note: rebuild PCF + retest on device.\nStep 9: Log case B; suggest \u002Ftest-native-extension then \u002Fgenerate-pcf-companion publish path.\n```\n\n### Scenario 2 — Crash at launch (native load)\n\n```\nStep 2: Symptom = \"app crashes the moment the control's screen opens\", host log\n        \"Loaded 0 plugin package(s)\".\nStep 3: Triage → native-load + native-android.\nStep 4: Read the ReactPackage class — constructor takes an argument (no public no-arg\n        ctor). Matches error-codes.md §4 \"Loaded 0 plugin package(s)\".\nStep 5: [HIGH] ReactPackage has no public no-arg constructor → runtime instantiation fails\n        fails → 0 packages loaded. Gate: proceed.\nStep 6: Case B. Fix: add the public no-arg constructor.\nStep 7: Apply. 7.5: Gate 10 buildability clean.\nStep 8: Native-only → defer to \u002Fbuild-android-binary; rebuild + device retest required.\nStep 9: Log; recommend \u002Fgenerate-ppmplugin (rebuild + audit).\n```\n\n### Scenario 3 — Wrong output (behavior drift, spec is right)\n\n```\nStep 2: Symptom = \"Done returns the image without the drawing layer.\"\nStep 3: Triage → behavior\u002Fspec + native (both platforms).\nStep 4: Read both native op bodies vs ARCHITECTURE §3.n export step. Android composites\n        only the base bitmap; iOS composites both. Evidence: \u003CPascal>Module.kt:NN.\nStep 5: [HIGH] Android export omits the ink layer; ARCHITECTURE §3.1 says composite both.\n        Gate: proceed.\nStep 6: Case B (spec already correct). Fix Android export to match. Cross-platform parity.\nStep 7: Apply. 7.5: Gate 5 parity now holds.\nStep 8: Native-only → rebuild + device retest. Step 9: log; suggest \u002Fgenerate-ppmplugin.\n```\n\n---\n\n## Failure modes\n\n| What happens | What the skill does |\n|---|---|\n| PRD \u002F `package.json` missing | STOP with `BLOCKED: not an extension repo`; suggest `\u002Fgenerate-native-extension`. |\n| Symptom too thin to triage after one clarifying question | STOP with `NEEDS_CONTEXT: \u003Cwhat's needed>` (e.g. paste `\u003Cname>Json` \u002F a host log line). |\n| No hypothesis reaches ≥ MEDIUM confidence | STOP with `NEEDS_CONTEXT` — never fabricate a fix. |\n| User stops after diagnosis | `BLOCKED: user stopped after diagnosis`; diagnosis logged. |\n| User declines the fix plan | `BLOCKED: user declined fix plan`; diagnosis (and any doc edit already applied) logged. |\n| Fix requires PCF edits but no `pcf\u002F` | STOP; route to `\u002Fgenerate-pcf-companion`. |\n| Smoke check fails | `BLOCKED: smoke check failed — \u003Ccause>`; edits stay; log the failure. |\n| Edit tool fails (e.g. `old_string` not unique) | Surface the precise error; don't retry blindly; report which files applied. |\n\n---\n\n## Return status\n\nEnd every run with one of:\n\n- `DONE` — root cause located, fix applied, smoke check passed (or native-only with the rebuild+retest reminder printed).\n- `DONE_WITH_CONCERNS: \u003Clist>` — fix applied but with caveats (self-critique concerns, missing expected files, an unconfirmed secondary hypothesis).\n- `BLOCKED: \u003Creason>` — user stopped\u002Fdeclined, smoke check failed, PRD missing, or PCF needed but absent.\n- `NEEDS_CONTEXT: \u003Cwhat's unclear>` — symptom too thin, or no cause reached sufficient confidence.\n","# \u002Fdebug-extension\n\nInvestigate a failure the user observed while testing a **built** `.ppmplugin` control,\nfind the root cause, and fix it. The wrap binary runs inside the customer's shell with\n**no logcat \u002F Xcode console \u002F native debugger reachable**, so the evidence is usually just\nthe PCF's `ErrorCode` \u002F `ErrorMessage`, the raw `\u003Cname>Json` diagnostic output, a host log\nline, or the user's description of what they saw. This skill turns that thin evidence into\na located root cause and a fix.\n\n**Investigation-first, fix as the resolution.** Unlike a plain \"apply this change\" flow,\n`\u002Fdebug-extension` starts from a *symptom* and works backward to a *cause* before touching\ncode. When the cause is found, it proposes the fix and applies it under the same discipline\na careful edit uses (spec-vs-drift diagnosis, contract-consistency, surgical edits, gates).\n\n**This is one door, not the only door.** Per `shared\u002Fshared-instructions.md §7.5`, a fix\ncan be applied from *any* skill or a plain conversational turn — the user is never blocked\nor forced to route through this skill. What this skill adds is *structure* for a reported\nproblem: the symptom→layer triage, the dispatch-path trace, and the located-evidence\ndiagnosis before any edit. Reach for it when something *broke on device* and you don't yet\nknow why; for a planned feature change where you already know what to edit, just edit\ndirectly.\n\n**When to use:**\n- \"I tapped the button and nothing happened — no error, no UI.\" (silent no-op)\n- \"The PCF shows `ErrorCode: PARSE` \u002F `ErrorMessage: ...`.\" (a code to trace)\n- \"The app crashes the moment the screen loads.\" (crash-at-launch)\n- \"Host log says `Loaded 0 plugin package(s)`.\" (a native-load signature)\n- \"It works on iOS but does nothing on Android.\" (parity \u002F transport bug)\n- \"The Done button returns the wrong data.\" (behavior drift)\n\n**When NOT to use:**\n- No repo yet → `\u002Fgenerate-native-extension`.\n- A brand-new operation → `\u002Fdesign-native-extension-feature`, then generate.\n- A planned change with a known edit and no reported failure → just edit (any skill \u002F chat).\n- A build that never produced a binary → the failure is a *build* failure; run\n  `\u002Fgenerate-ppmplugin` and read its stage output first.\n\n**Decoupled from generate-*.** This skill refuses to run if no extension repo is detected.\nIt does NOT scaffold, install dependencies, build binaries, or assemble the bundle. It\ndiagnoses, then edits files.\n\n---\n\n## Step 0 — Verify this is an extension repo\n\nDetect the repo in this order. Stop with `BLOCKED: not an extension repo (no \u003CX> found)`\nif any **required** signal is missing.\n\n| Signal | Required? | Check |\n|---|---|---|\n| `PRD.md` exists at repo root | **Yes** | The spec is the baseline the observed behavior is compared against. |\n| `package.json` exists at repo root | **Yes** | Confirms this is a generated extension repo, not a random directory. |\n| `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. |\n| `.extension-state.md` exists at repo root | No | Informational — prior edits \u002F drift entries are debugging leads. Created at Step 9 if absent. |\n| `pcf\u002F` folder with a `ControlManifest.Input.xml` inside | No | Drives PCF detection. Use Glob under `pcf\u002F` to locate the manifest and capture `has_pcf: true|false`. |\n| `ppmplugin\u002F` build output \u002F a `.ppmplugin` artifact | No | Informational — confirms a binary was built (this skill debugs *built* controls). Absence → the failure may be pre-build; note it. |\n\nIf PRD or `package.json` is missing, suggest `\u002Fgenerate-native-extension` and stop.\n\n---\n\n## Step 1 — Read shared docs, PRD, ARCHITECTURE, manifest, and state\n\nIn this order:\n\n1. `shared\u002Fshared-instructions.md` — constants, return-status codes (`DONE` \u002F `DONE_WITH_CONCERNS` \u002F `BLOCKED` \u002F `NEEDS_CONTEXT`), safety rules.\n2. **`shared\u002Ferror-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.\n3. `shared\u002Fnaming-conventions.md` — maps PRD identity to file paths for the trace.\n4. `shared\u002Frepo-layout.md` — the expected file tree.\n5. `shared\u002Fppmplugin-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 \u002F load failures.\n6. `.\u002FPRD.md` — full read (identity, operations, expected behavior).\n7. `.\u002FARCHITECTURE.md` — full read (SDK pin, per-op impl walkthroughs, message contract, §5 error codes, manifest impl). The trace follows this.\n8. `.\u002Fmanifest.json` — the committed dispatch contract (`name`, `receivers[].method`, `receivers[].nativeModule`).\n9. `.\u002F.extension-state.md` — prior `## Edits` \u002F `## Debug` entries and any recorded drift — often the fastest lead.\n\n**Skip `shared\u002Fprereq-check.md`.** Debug installs\u002Fauths nothing. If a fix later needs the\nPCF `npm run build`, Step 8 surfaces a missing toolchain then.\n\nPer `shared-instructions.md §9.2`, print a one-line prereq notice at the start of Step 1:\n\n```\nPrereq check — \u002Fdebug-extension: skipped (skill does no installs \u002F auth \u002F network — investigation only until a fix's smoke check).\n```\n\n---\n\n## Step 2 — Capture the bug report\n\nGather the symptom. If the user invoked the skill with no detail, prompt for it — ask for\nwhichever of these they have (one consolidated prompt, not five):\n\n- **What happened vs. what they expected** (the observable behavior).\n- **`ErrorCode` \u002F `ErrorMessage`** shown on the PCF (or in Power Fx via `Self.ErrorCode` \u002F `Self.ErrorMessage`).\n- **The raw `\u003Cname>Json`** diagnostic output (the wire bytes — transport-level forensics).\n- **Any host log line** (e.g. `Loaded 0 plugin package(s)`, `native module '\u003Cx>' not loaded`, `method '\u003Cm>' not found`, a stack trace).\n- **Platform** (iOS \u002F Android \u002F both) and **when** it happens (at launch \u002F on tap \u002F after the operation).\n- **Repro steps**, if any.\n\nKeep the raw report in working context for the trace — do not paraphrase away detail, since\nan exact code or message is the highest-signal input. **Do not persist it verbatim.**\n`.extension-state.md` is committed to the repo, and a pasted report routinely carries a raw\nresponse, stack trace, host log lines, file paths, URLs, tokens, or customer data. Step 9\nwrites a redacted one-line summary instead — see the redaction rule there.\n\n---\n\n## Step 3 — Triage: map the symptom to candidate layers\n\nUsing **`shared\u002Ferror-codes.md`** (§2 module codes, §3 transport codes, §4 no-code\nsignatures), classify the symptom into one or more **candidate layers**, most-likely first:\n\n| Layer | Reached when the symptom looks like… |\n|---|---|\n| **PCF \u002F transport** (`pcf\u002F\u003CPascal>PCF\u002Findex.ts`) | `PARSE`, `UNEXPECTED_PAYLOAD`, `BRIDGE_FAILED`, `NOT_IN_WRAP`; silent no-op on tap; every call fails identically. |\n| **Dispatch contract** (`.\u002Fmanifest.json` ↔ native names ↔ PCF key) | `method '\u003Cm>' not found`, `native module '\u003Cx>' not loaded`, `BRIDGE_FAILED` with a routing message; works on one platform only. |\n| **Native module — Android** (`android\u002F...\u002F\u003CPascal>Module.kt`) | `INTERNAL_ERROR` \u002F `PERMISSION_DENIED` \u002F `NO_ACTIVITY` on Android; Android-only crash; `Loaded 0 plugin package(s)`. |\n| **Native module — iOS** (`ios\u002FRCT\u003CPascal>Module.m`) | `INTERNAL_ERROR` \u002F `PERMISSION_DENIED` on iOS; iOS-only crash \u002F no-op; `+moduleName` \u002F `requiresMainQueueSetup` load issue. |\n| **Native load \u002F lifecycle** (constructor, package class) | Crash **at launch** before any UI; module never loads. |\n| **Build config \u002F RN pin** (`package.json`, `android\u002Fbuild.gradle`, `.podspec`) | React header \u002F undefined-symbol errors; behavior tied to an SDK level; a pin divergence from the host RN. |\n| **Behavior \u002F spec** (native op body vs PRD\u002FARCHITECTURE) | Wrong result, missing control, incorrect payload — no error code, just wrong output. |\n\nA single report can span layers (e.g. `UNEXPECTED_PAYLOAD` is *usually* PCF, but *can* be a\nnon-conforming native response). List every plausible layer; Step 4 confirms\u002Feliminates.\n\nIf the report is too thin to triage, ask **one** targeted clarifying question (e.g. \"Does\nit fail on both platforms or just one?\"). If still unclear, stop with\n`NEEDS_CONTEXT: \u003Cwhat's unclear>`.\n\n---\n\n## Step 4 — Investigate: trace the path and gather evidence\n\nFor each candidate layer, read the implicated files and confirm or eliminate the hypothesis\nwith concrete evidence. Do NOT guess — open the file and cite the line.\n\nConvention-derived files (substitute `\u003CPascal>` \u002F `\u003Clower>` from PRD identity via\n[`shared\u002Fnaming-conventions.md`](..\u002F..\u002Fshared\u002Fnaming-conventions.md)):\n\n- **PCF \u002F transport** → `pcf\u002F\u003CPascal>PCF\u002Findex.ts` (`invokeBridge`, `extractResponse`, `onTrigger` outcome branch, `args: [request]`, the composite key), `pcf\u002F\u003CPascal>PCF\u002FControlManifest.Input.xml`.\n- **Dispatch contract** → `.\u002Fmanifest.json` `receivers[]`; native `getName()` (Android) \u002F `+moduleName` (iOS); the PCF composite key `\u003Cname>\u002F\u003Creceiver>` + `method`. Cross-check all three agree.\n- **Native Android** → `android\u002Fsrc\u002Fmain\u002Fjava\u002Fcom\u002Fpowerapps\u002F\u003Clower>\u002F\u003CPascal>Module.kt` (+ `\u003CPascal>CaptureActivity.kt`), the `ReactPackage` class (public no-arg constructor), `android\u002Fsrc\u002Fmain\u002FAndroidManifest.xml`.\n- **Native iOS** → `ios\u002FRCT\u003CPascal>Module.{h,m}` (`+moduleName`, `+requiresMainQueueSetup`, no-arg init), the presented VC.\n- **Build \u002F pin** → `package.json` (RN pin `0.79.7`), `android\u002Fbuild.gradle`, `ios\u002F\u003CPascal>Extension.podspec`.\n\nTrace techniques:\n- **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.\n- **Grep for the specific symbol** in the report (an error code, a field name, a method name) across `ios\u002F`, `android\u002F`, `pcf\u002F` to find every site that emits or consumes it.\n- **Compare iOS vs Android** when the symptom is platform-specific — the delta is the lead.\n- **Check the raw `\u003Cname>Json`** against the `{ status, result?\u002Ferror?, message? }` convention and the wrap `{ isUpdate, message }` container — a shape mismatch points to `extractResponse` vs a bare parse.\n- **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.\n\nRead `shared\u002Fself-critique-protocol.md` if the trace touches a per-operation impl — its\ngates (state coverage, cross-platform parity, lifecycle) sharpen the hypotheses.\n\n---\n\n## Step 5 — Root-cause diagnosis + gate\n\nPresent a ranked diagnosis. Each hypothesis is anchored in evidence, not intuition:\n\n```\nDiagnosis for: \"\u003Cverbatim symptom>\"\n\n1. [HIGH confidence] \u003Cone-line root cause>\n   Evidence: \u003Cfile>:\u003Cline> — \u003Cwhat the code does \u002F doesn't do>\n   Why it produces this symptom: \u003Cone sentence tied to error-codes.md>\n   Layer: PCF | dispatch contract | native-android | native-ios | native-load | build\u002Fpin | behavior\n\n2. [MEDIUM confidence] \u003Calternative cause>\n   Evidence: ...\n\nRuled out: \u003Chypothesis> — \u003Cwhy the evidence eliminates it>\n\nRecommended fix (for #1): \u003Cwhat would change, in which file(s)>\n```\n\n**Gate**: `Proceed with the fix for #1? (yes \u002F investigate #2 instead \u002F show me \u003Cfile> \u002F stop)`.\n\n- On `stop` → `BLOCKED: user stopped after diagnosis` (nothing edited; diagnosis logged at Step 9).\n- On `investigate #2` → deepen that hypothesis, re-present.\n- If **no** hypothesis reaches at least MEDIUM confidence after the trace → stop with\n  `NEEDS_CONTEXT: \u003Cwhat additional evidence is needed>` (e.g. \"please paste the raw\n  `\u003Cname>Json` output\" or \"a host log line from the crash\"). Never fabricate a fix for an\n  unconfirmed cause.\n\n---\n\n## Step 6 — Fix plan + spec-vs-drift check + gate\n\nNow derive the fix. First classify it the same way a careful edit does, because a fix can\nbe more than a code patch:\n\n| Case | What the fix is | Action |\n|---|---|---|\n| **B — code drift** (most common) | The code diverged from a spec that is already correct (e.g. a missing `extractResponse`, a wrong composite key, a swallowed exception). | Fix the code only. Print `\u003Cdoc> §\u003Cn> already specifies the correct behavior — fixing code only.` |\n| **A — spec wrong** | The observed behavior is actually what PRD\u002FARCHITECTURE currently says, but that spec is wrong. | Propose the PRD\u002FARCHITECTURE edit **first** (its own mini-gate), apply it, then derive the code. |\n| **C — both** | Spec is ambiguous\u002Fpartial and code is partial. | Update the doc detail, then fix the code. |\n\nThen present the code fix plan:\n\n```\nFix plan:\n\n\u003Cpath\u002Fto\u002Ffile>\n  - Replace: \u003Cspecific symbol \u002F region> → \u003Creplacement> (rationale tied to the diagnosis)\n  - Add:     \u003Cspecific addition>\n\nContract impact: \u003C\"none\" | \"method set \u002F receiver \u002F nativeModule moves — .\u002Fmanifest.json + PCF key updated in this same change, re-staged via \u002Fgenerate-ppmplugin-manifest\">\nTotal: N files changed.\nApply? (yes \u002F no \u002F show me \u003Cfile>)\n```\n\n**Contract seam.** If the fix changes the method set, the receiver\u002Frouting name, or the\nnative-module name (Android `getName()` \u002F iOS `+moduleName` = `\u003CPascal>Module`), three\nartifacts move **together** in this fix: native source, the committed `.\u002Fmanifest.json`\n(`receivers[]` \u002F `methods`, edited surgically), and the PCF composite key `\u003Cname>\u002F\u003Creceiver>`.\nThen `\u002Fgenerate-ppmplugin-manifest` re-validates + re-stages the manifest. A pure-behavior\nfix that leaves those unchanged does not touch the manifest.\n\nIf the fix requires PCF edits but `has_pcf: false`, stop with `BLOCKED: this fix requires\nPCF edits but pcf\u002F is not scaffolded — run \u002Fgenerate-pcf-companion first`.\n\n**Gate**: wait for explicit `yes`. On `no` → `BLOCKED: user declined fix plan` (diagnosis\nstill logged). On `show me \u003Cfile>` → print the proposed content and re-ask.\n\n---\n\n## Step 7 — Apply the fix\n\nApply the planned edits with the `Edit` tool. Rules:\n\n- **Surgical, not wholesale.** Change the lines the diagnosis identified; don't rewrite the\n  function or file. Reserve `Write` for a genuinely new file (rare in debug).\n- **Atomic per file.** Apply all edits to one file in sequence; never leave a file\n  half-edited.\n- **Atomic across files (best effort).** If a multi-file batch fails mid-way, stop, report\n  which files were written and which weren't, and tell the user to `git diff` \u002F `git\n  checkout` the half-written ones. Do NOT auto-revert (destructive, not on the safe list).\n- **No collateral edits.** Only touch files on the plan. Note unrelated issues in the\n  summary; don't fix them in this pass.\n\n---\n\n## Step 7.5 — Self-critique against the proactive protocol\n\nAfter applying, re-read every touched file and walk\n[`shared\u002Fself-critique-protocol.md`](..\u002F..\u002Fshared\u002Fself-critique-protocol.md). A fix that\nresolves the reported symptom can introduce a new one (fixing an Android crash by deferring\ninit might leave a first-call race; correcting the composite key might orphan an output).\n\n1. **Re-read** each edited file fresh from disk (not from memory).\n2. **Walk the gates** — PRD coverage, user journey, layout, state, cross-platform parity,\n   reversibility, lifecycle, spec-drift, plus the 3P Gates 10 (buildability \u002F bundle-fit)\n   and 11 (PCF↔native round-trip). Pay special attention to **Gate 11** — most debug fixes\n   touch the very round-trip that broke.\n3. **Report + apply fixes** per the protocol's severity\u002Fautofix cadence: mechanical fixes in\n   one batch (one `yes`); structural fixes each gated; judgment calls surfaced as concerns.\n   Re-loop up to 3 iterations.\n\nReturn-status impact: all gates clean → continue. Blockers deferred → `BLOCKED:\nself-critique blockers — \u003Clist>` (fix stays applied; user re-runs after deciding).\nConcerns remain → continue with `DONE_WITH_CONCERNS`.\n\n---\n\n## Step 8 — Verify the fix\n\nVerify the fix actually addresses the symptom, scoped to what was edited:\n\n**Validate before you interpolate.** `\u003CPascal>` comes from PRD identity, not from a constant —\na crafted or malformed value turns the command below into arbitrary shell or escapes the\nproject directory. Before running it: require `\u003CPascal>` to match `^[A-Za-z][A-Za-z0-9]*$`\n(no separators, dots, or path segments), resolve `pcf\u002F\u003CPascal>PCF` and confirm the real path\nstays inside `pcf\u002F`, then pass it as a single quoted argument rather than splicing it into\nshell syntax. On failure, STOP with `BLOCKED: refusing to run a build command with an invalid\n\u003CPascal> value — \u003Cvalue>`.\n\n| Files edited | Verification | Why |\n|---|---|---|\n| Any `pcf\u002F\u003CPascal>PCF\u002F` `.ts` \u002F `ControlManifest.Input.xml` | `npm run build --prefix \"$PCF_DIR\"` | The only TS build in the repo — catches type + manifest errors immediately. |\n| Only `.kt` \u002F `.m` \u002F XML | Print: `Native files fixed — compile + on-device validation defer to \u002Fbuild-android-binary \u002F\u002F \u002Fbuild-ios-binary (via \u002Fgenerate-ppmplugin) and \u002Ftest-native-extension Layer 5. Rebuild + retest on device to confirm the symptom is gone.` | Native standalone compile isn't reliable here; the build skills do the real compile. |\n| Contract moved (`.\u002Fmanifest.json` \u002F names) | Re-run `\u002Fgenerate-ppmplugin-manifest` (re-validate + re-stage), then note that `\u002Fgenerate-ppmplugin` (rebuild + `\u002Faudit-ppmplugin`) is needed. | The staged manifest and the binary must be regenerated for the fix to reach the device. |\n\n**The definitive verification for a field bug is a rebuild + on-device retest** — a passing\nsmoke check confirms the fix compiles, not that the symptom is gone. Say so explicitly in\nthe summary. On smoke-check failure: report the failing command + the most relevant error\nline, do NOT auto-revert, stop with `BLOCKED: smoke check failed — \u003Cone-line cause>` (still\nlog at Step 9).\n\n---\n\n## Step 9 — State log + summary\n\n### 9.1 Update `.extension-state.md`\n\nAppend (don't overwrite) to a `## Debug` section (create it if absent):\n\n```markdown\n## Debug\n\n- \u003CISO timestamp> — \u003Cone-line summary of the bug + fix>\n  - Symptom: \"\u003Credacted one-line summary — see the redaction rule below>\"\n  - Root cause: \u003Clocated cause> (\u003Cfile>:\u003Cline>)\n  - Diagnosis case: A | B | C\n  - Docs changed: \u003Csections, or \"none\">\n  - Code changed: \u003Cfile paths>\n  - Contract moved: \u003C\"none\" | \"receiver\u002Fmethod\u002FnativeModule changed — .\u002Fmanifest.json updated; re-staged via \u002Fgenerate-ppmplugin-manifest\">\n  - Verification: \u003CPCF npm run build → PASS | native — rebuild + device retest required | etc.>\n  - Status: DONE | DONE_WITH_CONCERNS: \u003Creasons> | BLOCKED — \u003Creason>\n```\n\n**Redact before writing.** `.extension-state.md` is committed to the repo, so treat every\nfield as published. The `Symptom` line is a short paraphrase — the error code, the affected\noperation, and the observable behaviour — never the pasted report. Strip, from every field:\nsecrets and tokens; PII and customer data; request\u002Fresponse payloads and their fragments;\nabsolute or internal filesystem paths; internal URLs and hostnames; and stack traces beyond\nthe single frame that locates the cause. Keep `Root cause` to the repo-relative `\u003Cfile>:\u003Cline>`\nthat already lives in source control. If a detail is needed to justify the fix but can't be\nredacted safely, leave it out of the file and keep it in the chat.\n\n### 9.2 Final summary + next step\n\nOne paragraph: the located root cause, what was fixed, and the verification outcome — and\n**state plainly that an on-device retest (after a rebuild) is what confirms the symptom is\nresolved**. Then offer the next step via `AskUserQuestion` (shared-instructions §9.1),\npicking the options that fit the fix:\n\n- **Run \u002Fgenerate-ppmplugin** — rebuild the `.ppmplugin` + re-audit (re-validates + re-stages `.\u002Fmanifest.json` first). The recommended next step for a native or contract fix.\n- **Run \u002Ftest-native-extension** — re-validate the contract (Layer 0 cross-check; Layer 4 PCF compile). Good for a PCF or contract fix before the full rebuild.\n- **Run \u002Fgenerate-pcf-companion** — only if the fix needs PCF edits but `pcf\u002F` isn't scaffolded.\n- **Stay — I'll retest on device first.**\n\nPer the **Execute, don't describe** HARD RULE (§9.1), when the user picks a `Run \u002F…` option,\ninvoke that skill via the `Skill` tool in the same turn. Don't *auto*-chain on your own.\n\n---\n\n## Hard rules\n\n1. **Never fix without a located cause.** Every fix traces to file:line evidence from\n   Step 4\u002F5. No confirmed cause → `NEEDS_CONTEXT`, not a speculative patch.\n2. **Two gates: diagnosis, then fix plan.** Never edit code silently. On a case-A\u002FC spec\n   fix, the doc edit gets its own mini-gate first.\n3. **Never blow away unrelated files.** Only files on the Step 6 plan are touched — no\n   drive-by refactors.\n4. **Never auto-revert on failure.** Surface it, stop; the user reviews `git diff`.\n5. **File-edit policy — three categories** (identical to the generate\u002Fedit discipline):\n   - **Tool-managed — NEVER edit:** `.git\u002F`, lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `Podfile.lock`), the generated bundle + its staging (`ppmplugin\u002Fstaging\u002Fmanifest.json`, `ppmplugin\u002F` outputs, any `.ppmplugin`), PCF generated artifacts (`pcf\u002F\u003CPascal>PCF\u002Fgenerated\u002F`), build outputs (`lib\u002F`, `dist\u002F`, `build\u002F`, `pcf\u002F\u003CPascal>PCF\u002Fout\u002F`), `*.bak.*`, `.claude\u002F`. (The committed `.\u002Fmanifest.json` at repo root is the opposite — a consumer site you DO edit when the contract moves.)\n   - **Skill-managed — updated only via the canonical state step:** `.extension-state.md` (this skill's Step 9). No mid-flow direct edits.\n   - **User-editable on request:** `.gitignore`, `CHANGELOG.md`, `LICENSE`, `README.md`, PCF `eslint.config.js` \u002F `tsconfig.json`, and all source (`ios\u002F**`, `android\u002F**`, `pcf\u002F\u003CPascal>PCF\u002F{index.ts,ControlManifest.Input.xml}`).\n6. **Atomic per file, best-effort across files.**\n7. **Contract stays consistent.** If a fix moves the method set \u002F receiver \u002F nativeModule,\n   `.\u002Fmanifest.json` + native + PCF move together, then re-stage via\n   `\u002Fgenerate-ppmplugin-manifest`. Verify with `\u002Ftest-native-extension` Layer 0.\n8. **Spec and code stay in sync.** A case-A\u002FC fix updates PRD\u002FARCHITECTURE first; a case-B\n   fix logs the drift as such. Never silently update the spec to match a bug.\n9. **PCF is auto-detected, never assumed.** No `pcf\u002F\u003CPascal>PCF\u002FControlManifest.Input.xml`\n   → don't write to `pcf\u002F`; route to `\u002Fgenerate-pcf-companion` if the fix needs it.\n10. **Don't *auto*-chain; do honor an explicit pick** at Step 9.2.\n11. **A smoke check is not an on-device confirmation.** Always tell the user the fix must be\n    rebuilt and retested on device to confirm the field symptom is gone.\n\n---\n\n## Scenarios — how the flow plays out\n\n### Scenario 1 — Silent no-op on Android (PCF transport bug)\n\n```\nStep 2: Symptom = \"tap does nothing, no error, only on Android.\"\nStep 3: Triage → PCF\u002Ftransport (error-codes.md §4 top row) + dispatch contract.\nStep 4: Read pcf\u002F...\u002Findex.ts — invokeBridge calls cordova.exec directly, no sendAsync.\n        Evidence: index.ts:NN. Matches the §4 signature (cordova undefined in PCF sandbox).\nStep 5: [HIGH] cordova.exec used instead of the host-injected sendAsync → silent no-op,\n        worst on Android. Gate: proceed.\nStep 6: Case B (ppmplugin-format §2 already specifies sendAsync). Fix plan: replace\n        cordova.exec with window.PowerApps.NativeExtension.sendAsync + args:[request].\nStep 7: Apply. 7.5: self-critique Gate 11 (round-trip) clean.\nStep 8: cd pcf && npm run build → PASS. Note: rebuild PCF + retest on device.\nStep 9: Log case B; suggest \u002Ftest-native-extension then \u002Fgenerate-pcf-companion publish path.\n```\n\n### Scenario 2 — Crash at launch (native load)\n\n```\nStep 2: Symptom = \"app crashes the moment the control's screen opens\", host log\n        \"Loaded 0 plugin package(s)\".\nStep 3: Triage → native-load + native-android.\nStep 4: Read the ReactPackage class — constructor takes an argument (no public no-arg\n        ctor). Matches error-codes.md §4 \"Loaded 0 plugin package(s)\".\nStep 5: [HIGH] ReactPackage has no public no-arg constructor → runtime instantiation fails\n        fails → 0 packages loaded. Gate: proceed.\nStep 6: Case B. Fix: add the public no-arg constructor.\nStep 7: Apply. 7.5: Gate 10 buildability clean.\nStep 8: Native-only → defer to \u002Fbuild-android-binary; rebuild + device retest required.\nStep 9: Log; recommend \u002Fgenerate-ppmplugin (rebuild + audit).\n```\n\n### Scenario 3 — Wrong output (behavior drift, spec is right)\n\n```\nStep 2: Symptom = \"Done returns the image without the drawing layer.\"\nStep 3: Triage → behavior\u002Fspec + native (both platforms).\nStep 4: Read both native op bodies vs ARCHITECTURE §3.n export step. Android composites\n        only the base bitmap; iOS composites both. Evidence: \u003CPascal>Module.kt:NN.\nStep 5: [HIGH] Android export omits the ink layer; ARCHITECTURE §3.1 says composite both.\n        Gate: proceed.\nStep 6: Case B (spec already correct). Fix Android export to match. Cross-platform parity.\nStep 7: Apply. 7.5: Gate 5 parity now holds.\nStep 8: Native-only → rebuild + device retest. Step 9: log; suggest \u002Fgenerate-ppmplugin.\n```\n\n---\n\n## Failure modes\n\n| What happens | What the skill does |\n|---|---|\n| PRD \u002F `package.json` missing | STOP with `BLOCKED: not an extension repo`; suggest `\u002Fgenerate-native-extension`. |\n| Symptom too thin to triage after one clarifying question | STOP with `NEEDS_CONTEXT: \u003Cwhat's needed>` (e.g. paste `\u003Cname>Json` \u002F a host log line). |\n| No hypothesis reaches ≥ MEDIUM confidence | STOP with `NEEDS_CONTEXT` — never fabricate a fix. |\n| User stops after diagnosis | `BLOCKED: user stopped after diagnosis`; diagnosis logged. |\n| User declines the fix plan | `BLOCKED: user declined fix plan`; diagnosis (and any doc edit already applied) logged. |\n| Fix requires PCF edits but no `pcf\u002F` | STOP; route to `\u002Fgenerate-pcf-companion`. |\n| Smoke check fails | `BLOCKED: smoke check failed — \u003Ccause>`; edits stay; log the failure. |\n| Edit tool fails (e.g. `old_string` not unique) | Surface the precise error; don't retry blindly; report which files applied. |\n\n---\n\n## Return status\n\nEnd every run with one of:\n\n- `DONE` — root cause located, fix applied, smoke check passed (or native-only with the rebuild+retest reminder printed).\n- `DONE_WITH_CONCERNS: \u003Clist>` — fix applied but with caveats (self-critique concerns, missing expected files, an unconfirmed secondary hypothesis).\n- `BLOCKED: \u003Creason>` — user stopped\u002Fdeclined, smoke check failed, PRD missing, or PCF needed but absent.\n- `NEEDS_CONTEXT: \u003Cwhat's unclear>` — symptom too thin, or no cause reached sufficient confidence.\n",{"name":5,"model":32,"description":7,"allowed-tools":50},"Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Skill","main","0a55a88fa2855404029d1e5450faf92878baf763","plugins\u002Fpower-apps-mobile-extension\u002Fskills\u002Fdebug-extension",232,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills","https:\u002F\u002Fmicrosoft.github.io\u002Fpower-platform-skills\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-14 21:46:39",{"source":8,"skillName":5,"commands":62,"prompt":72,"zipAvailable":73},[63,66,69],{"tool":64,"command":65},"npx","npx skills add microsoft\u002Fpower-platform-skills --skill debug-extension",{"tool":67,"command":68},"bunx","bunx skills add microsoft\u002Fpower-platform-skills --skill debug-extension",{"tool":70,"command":71},"pnpm","pnpm dlx skills add microsoft\u002Fpower-platform-skills --skill debug-extension","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fpower-apps-mobile-extension\u002Fskills\u002Fdebug-extension\u002FSKILL.md",true,[],[76,84,105,125,143,157],{"skillNo":77,"name":78,"nameZh":6,"description":79,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":80,"categories":81,"keywords":82,"publishedAt":83},"01M78JN2BFRRV1J54Q6WKZQ08D","compare-site-configurations","Compare Power Pages site configurations between two environments, such as dev, test and production, or between a local download and the live site, and explain which differences change site behavior. Use when a site works in one environment but not another (for example, works in dev but fails in test), to check configuration drift before promoting or deploying, or to see what changed between two sites. Produces a shareable HTML report and a JSON file that VS Code can import.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fpower-pages\u002Fskills\u002Fcompare-site-configurations\u002FSKILL.md",[],[],"2026-11-15 14:19:17",{"skillNo":85,"name":86,"nameZh":6,"description":87,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":88,"categories":89,"keywords":90,"publishedAt":45},"01M699WVHX0XN59EPBTTPEKYPG","setup","Use when Process Intelligence needs building, explicit cloud\u002Faccount\u002Fenvironment configuration, sign-in, connection diagnostics, or recovery from an authentication error.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fprocess-intelligence\u002Fskills\u002Fsetup\u002FSKILL.md",[],[86,91,92,93,94,95,96,97,98,99,100,101,102,103,40,104],"configuration","diagnostics","error","environment","cloud","when","connection","authentication","use","Bash","recovery","process","sign","intelligence",{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":114,"publishedAt":45},"01M699WSR9EX55YY1WD9J22FEG","report-issue","Use when the user wants a Process Intelligence bug-report draft or support summary for a failed operation.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fprocess-intelligence\u002Fskills\u002Freport-issue\u002FSKILL.md",[111],{"categoryNo":112,"categoryName":113,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000034","行政与办公人员",[115,116,117,118,99,96,119,120,102,121,104,122,123,30,124],"issue","report","report issue","bug-report","operation","draft","bug","summary","user","support",{"skillNo":126,"name":127,"nameZh":6,"description":128,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":129,"categories":130,"keywords":131,"publishedAt":45},"01M699WR26YQ9Q21KE6MJF5B2G","investigate-process","Use when a broad Process Mining business question, observed pattern or competing explanation needs investigation across analytical perspectives.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fprocess-intelligence\u002Fskills\u002Finvestigate-process\u002FSKILL.md",[],[132,102,133,134,99,135,136,96,137,138,139,40,140,141,142],"investigate","investigate process","question","process mining","business","across","perspectives","mining","pattern","investigation","analytical",{"skillNo":144,"name":145,"nameZh":6,"description":146,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":147,"categories":148,"keywords":149,"publishedAt":45},"01M699WP9SDG5ZR12P8VYNXKTN","derive-metric","Use when a requested measure is missing, a saved custom metric needs reuse, or an ephemeral formula or derived scalar is needed.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fprocess-intelligence\u002Fskills\u002Fderive-metric\u002FSKILL.md",[],[150,151,152,153,154,155,99,96,156,40],"metric","derive metric","missing","formula","custom","reuse","saved",{"skillNo":158,"name":159,"nameZh":6,"description":160,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":161,"categories":162,"keywords":163,"publishedAt":45},"01M699WMG5R8P6SMTDAS1TKF9E","compare-cohorts","Use when comparing process cohorts, departments, periods or before-and-after results under matched definitions.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fpower-platform-skills\u002Fblob\u002Fmain\u002Fplugins\u002Fprocess-intelligence\u002Fskills\u002Fcompare-cohorts\u002FSKILL.md",[],[164,165,99,96,166,102,40],"compare","compare cohorts","results"]