[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M69BSV4V52VBDF3RZ3E6Y61T":3,"skill-same:01M69BSV4V52VBDF3RZ3E6Y61T":88},{"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":28,"publishedAt":50,"linkOnly":51,"markdownContent":52,"markdownBody":53,"frontMatter":54,"refName":55,"commitSha":56,"skillDirectory":57,"forksCount":58,"repositoryHtmlUrl":59,"repositoryHomepageUrl":6,"ownerHtmlUrl":60,"ownerBlogUrl":61,"ownerDescription":62,"updatedAt":63,"install":64,"resources":77},"01M69BSV4V52VBDF3RZ3E6Y61T","ux-pr-review",null,"Prepare and run an agent-assisted UX \u002F workflow review of a pull request. Use when the operator says \"I'm about to work on a UX PR review, please prepare\", \"prepare a UX review for PR","microsoft\u002Fvscode-documentdb","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M69BRX0BQJ0QGRNCNZAAAXBV",33,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fux-pr-review\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000032","设计师","PROFESSION","适用职业",[29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,49],"pr review","pr","ux pr review","ux","review","operator","when","request","for","about","please","workflow review","use","ux review","work","work on","pull","run","pull request","prepare","workflow","2026-11-10 10:12:30",false,"---\nname: ux-pr-review\ndescription: Prepare and run an agent-assisted UX \u002F workflow review of a pull request. Use when the operator says \"I'm about to work on a UX PR review, please prepare\", \"prepare a UX review for PR #NNN\", \"review the UX of this branch\u002Ffeature\", or when pairing on a hands-on review where a person exercises the extension and the agent verifies findings against the code. The agent pre-seeds a structured review document (with a user-interaction diagram and a pre-discovered inconsistency list), then drives a live, iterative review loop grouped by severity. Does NOT cover pure code review (see CONTRIBUTING.md §6.1) or release notes (see writing-release-notes).\n---\n\n# UX PR Review (agent-assisted)\n\nA UX review is different from a code review: the value comes from **actually using the\nextension and walking real user journeys**, not from reading a diff. The pattern is a\n**person paired with an agent** — the person drives the UX and reports what they see; the\nagent reads the code, verifies each claim against it, keeps the running log, and maintains\nthe todo list.\n\nThis skill has **two modes**:\n\n1. **Prepare (pre-assessment)** — triggered up front. The agent inventories the feature's\n   user interactions, draws where each flow **starts and terminates**, pre-discovers\n   **flow inconsistencies** (modal vs. non-modal vs. silent), seeds the review document,\n   and hands off to the operator with an executive summary.\n2. **Live review** — the operator exercises the feature and dictates observations; the\n   agent verifies against code, records each finding, and keeps the priority index + todo\n   list current.\n\n> The full document skeleton lives in [references\u002Freview-document-template.md](.\u002Freferences\u002Freview-document-template.md).\n> The pre-discovery checklist lives in [references\u002Finconsistency-checklist.md](.\u002Freferences\u002Finconsistency-checklist.md).\n> Worked examples: [`docs\u002Fai-and-plans\u002Ffeatures\u002Fkubernetes-discovery\u002Fiterations\u002F01-kubernetes-discovery\u002Fbugbash-090-ux-review.md`](..\u002F..\u002F..\u002Fdocs\u002Fai-and-plans\u002Ffeatures\u002Fkubernetes-discovery\u002Fiterations\u002F01-kubernetes-discovery\u002Fbugbash-090-ux-review.md) and [`docs\u002Fai-and-plans\u002Ffeatures\u002Findex-management\u002Fiterations\u002F01-index-dashboard\u002Fux-review-iteration-1-2.md`](..\u002F..\u002F..\u002Fdocs\u002Fai-and-plans\u002Ffeatures\u002Findex-management\u002Fiterations\u002F01-index-dashboard\u002Fux-review-iteration-1-2.md).\n\n## When to Use\n\n- The operator asks to **prepare** a UX review, or says they are about to start one.\n- Reviewing the UX\u002Fworkflow of a PR, branch, or feature by hand.\n- Pairing live: the operator reports what they saw and asks you to investigate and update\n  the todo list \u002F review doc.\n\n---\n\n## Mode 1 — Prepare (do this when asked to \"prepare\")\n\nWork through these steps, then stop and hand off. **Do not start critiquing individual\npixels yet** — the goal is to give the operator a seeded document and a map of the flows.\n\n### Step 1 — Identify the review target\n\nDetermine the PR number, branch, and the **feature surface** (the source folders that\nimplement it). If not given, ask which PR\u002Fbranch. Read `package.json` menus\u002Fcommands, the\ntree items, the webview components, and the command handlers for that surface.\n\n### Step 2 — Inventory the user interactions\n\nList every place the user can **act** on this feature: tree nodes and their context menus,\nempty-state rows, wizard steps \u002F quick picks, webview buttons, commands, drag-and-drop.\nFor each, note the **entry point** (how the user gets there) and the **terminal state**\n(success, error, silent no-op, dialog, tree refresh, new panel).\n\n### Step 3 — Draw where flows start and terminate\n\nProduce a **Mermaid `flowchart`** in the document's \"User interaction map\" section: nodes\nfor each user action\u002Fstate, edges for transitions, and **explicit terminal nodes** for\nevery outcome (success toast, modal error, silent no-op, tree badge). Mark inconsistent\nterminations so they stand out.\n\n```mermaid\nflowchart TD\n    A[User clicks 'Start'] --> B{Container ours & alive?}\n    B -- yes --> C[Starting… → Running badge]\n    B -- missing --> D([SILENT no-op ⚠️ only output channel])\n    B -- not ours --> E([Modal warning])\n```\n\nThe point of the diagram is to make **asymmetric terminations obvious**: if one branch\nends in a modal, another in a passive tree row, and a third in nothing at all, the diagram\nshould show it at a glance.\n\n### Step 4 — Pre-discover flow inconsistencies\n\nBefore the operator touches the feature, sweep the code for the inconsistencies UX reviews\nmost often catch (full list in [references\u002Finconsistency-checklist.md](.\u002Freferences\u002Finconsistency-checklist.md)).\nThe headline one:\n\n> **Error\u002Ffeedback surface inconsistency** — the same _class_ of event is surfaced three\n> different ways across the feature: sometimes a **modal** (`showErrorMessage(…, { modal: true })`),\n> sometimes a **non-modal** toast\u002Fwarning, sometimes a **passive tree row**, and sometimes\n> **nothing at all** (a silent early-return with only output-channel text). List every\n> occurrence with its file reference and flag the divergences. The house style across\n> shipped discovery providers is: **errors → modal + output channel; tree rows → actions\n> only; a single canonical \"Click here to retry\" node.**\n\nSeed these as **Flag** items in the document so the operator can confirm them live.\n\n### Step 5 — Seed the review document\n\nCreate the file at **`docs\u002Fai-and-plans\u002Ffeatures\u002F{feature}\u002Fiterations\u002FNN-{slug}.md`** (or\n`...\u002Fiterations\u002FNN-{slug}\u002Fux-review.md` when that iteration already holds several documents).\nPick the feature from the index in\n[`docs\u002Fai-and-plans\u002FREADME.md`](..\u002F..\u002F..\u002Fdocs\u002Fai-and-plans\u002FREADME.md); create a new feature folder\nwith a README if none fits. Use the full skeleton in\n[references\u002Freview-document-template.md](.\u002Freferences\u002Freview-document-template.md):\nheader block, \"How this review was run\", the **Legend** (Priority + Status + Markers), the\n**User interaction map** (the diagram from Step 3), \"The story in one paragraph\", the\n**Priority index** table, the P0→P3 + Implemented section stubs (pre-filled with the Step-4\nFlags as `? Open`), an **Open ideas** section, and an **Appendix** for the flow reference.\n\n> This document is committed. `docs\u002Fai-and-plans\u002F` is tracked — do **not** place it in\n> `docs\u002Fplan\u002F` or `docs\u002Fanalysis\u002F` (those are git-ignored). Never `git add -f`.\n\n### Step 6 — Executive summary + hand-off\n\nEnd your turn with a short **executive summary of the pre-assessment**:\n\n- the feature surface and the flows you mapped;\n- how many pre-discovered Flags you seeded, grouped by suspected severity;\n- the top inconsistencies to confirm (especially error-surface asymmetry);\n- **where the seeded file is**, and an explicit invitation: _\"The pre-seeded review doc is\n  at `\u003Cpath>`. Start the hands-on investigation — exercise the feature and tell me what you\n  see; I'll verify each observation against the code and keep the doc and todo list\n  updated.\"_\n\nDo not proceed to deep per-item analysis until the operator starts driving.\n\n---\n\n## Mode 2 — Live review loop\n\nFor each observation the operator reports:\n\n1. **Verify against code.** Trace the exact code path that produces the behavior. Never\n   record a finding you have not confirmed in the source.\n2. **Record the item** in the correct priority section using the four-part shape:\n   - **Observation** — what the reviewer saw (their words).\n   - **Finding** — what the code does and why, with file references and `⚠️`\u002F`?` markers.\n   - **Suggestion** (?) — the recommended direction. If the operator has a lean, capture it\n     as a blockquote _\"TN leans towards … because …\"_ and keep the status **Open** (it is a\n     suggestion, not a decision).\n   - **Status** — ? Open \u002F ? Open (soft) \u002F ✅ Implemented.\n3. **Update the Priority index** table and the **todo list** (`manage_todo_list`) so the\n   operator always sees remaining items at a glance.\n4. **Heavy trade-offs → Open ideas.** When a finding has real design options, add an\n   `O#` entry with a **pros\u002Fcons table** and a suggested option rather than deciding inline.\n5. **Out-of-scope → issues.** If a finding is beyond the PR's scope or would risk delaying\n   the merge, offer to file a repo issue and link it from the log instead of expanding scope.\n6. **Phase the work.** Review one user journey at a time (first-run\u002Fempty state → adding →\n   presentation → connectivity → destructive actions), closing each out before the next, so\n   context stays lean.\n\nIf the operator asks for tests to lock in an agreed behavior, add them as the finding lands.\n\n---\n\n## Mode 3 — Fixing in iterations\n\nOnce the operator starts choosing fixes, the review runs in **iterations**. Each iteration\nis a numbered pass over the open items; anything **not resolved in an iteration is carried\nforward to the next one** so nothing is ever silently dropped. The document is the ledger:\nan item leaves it only by becoming **Implemented**, **Closed** (won't-fix, with a reason),\nor **filed as a repo issue** (with a link).\n\n### The iteration loop\n\n1. **Group the current iteration.** Under an `## Iteration N` heading (or per-item\n   `➡️ Iteration N` sub-entries, as the K8s review does), list the items being worked this\n   pass. Everything still `? Open` after the pass rolls into `## Iteration N+1`.\n2. **Capture the decision — and its _reason_ — before coding.** When the operator picks a\n   fix, **ask them why**. Record their choice _and_ the reasoning inline on the item as a\n   **Decision** block:\n\n   > **Decision (Iteration N):** {{what was chosen}}. **Reason:** {{operator's rationale}}.\n\n   > **Remind the operator:** _\"This reasoning is the real value of the review — it's what\n   > lets future maintainers and contributors understand **why** the code looks the way it\n   > does. A one-line 'because …' now saves a re-litigation later.\"_ Never invent a\n   > rationale; if the operator hasn't given one, ask for it and wait.\n\n3. **Implement one item at a time.** Follow the code-review discipline in\n   [CONTRIBUTING.md](..\u002F..\u002F..\u002FCONTRIBUTING.md) §6.3: report progress inline; if you deviate\n   from the plan, document why; only proceed when confidence is high, otherwise stop and ask.\n   **Commit each item individually — no mass commits.**\n4. **Document the fix with a commit reference.** After the item is committed, flip its status\n   to `✅ Implemented` and append an **Implemented** block that says what changed, the files\n   touched, and a **link to the commit**:\n\n   > ✅ **Implemented (Iteration N):** {{what was done}}. Files: {{links}}.\n   > Commit: [`{{short-sha}}`]({{commit url}}). Verified via {{lint \u002F tests \u002F build}}.\n\n   If the fix answers a Copilot-reviewer comment or a repo issue, post the same summary there\n   and link it back from the item.\n\n5. **Carry forward the remainder.** At the end of the iteration, update the **Priority\n   index** (status column) and the **todo list** so every unresolved item is explicitly\n   parked in the next iteration. An item is never removed from the ledger without a terminal\n   status.\n\n### Terminal states for an item\n\n| Outcome                 | How it's recorded                                                            |\n| ----------------------- | ---------------------------------------------------------------------------- |\n| Fixed on this branch    | `✅ Implemented` + Decision block + Implemented block with commit link       |\n| Won't fix               | `? Closed` + a one-line **reason** (this reason is mandatory)               |\n| Deferred \u002F out-of-scope | Filed as a repo issue, `? Tracked` + issue link; removed from active P-list |\n| Still open              | Stays `? Open` and **moves to the next iteration**                          |\n\n### After merge\n\nStamp the log with a short reconciliation note pointing to the current source of truth (user\nmanual \u002F pre-merge code review), so a stale iteration is never mistaken for current behavior.\n\n---\n\n## Severity & status legend (use exactly these)\n\n**Priority**\n\n| Priority | Meaning                                            |\n| -------- | -------------------------------------------------- |\n| **P0**   | Blocking — the user gets stuck                     |\n| **P1**   | Broken \u002F misleading, or a consistency & safety gap |\n| **P2**   | Polish, expectation, or a smaller feature gap      |\n| **P3**   | Nice-to-have \u002F cosmetic \u002F acknowledged             |\n\n**Status**\n\n| Status             | Meaning                                                                  |\n| ------------------ | ------------------------------------------------------------------------ |\n| ? **Open**        | Recorded + analyzed; carries a recommendation but stays a _suggestion_   |\n| ? **Open (soft)** | Open, but the recommendation depends on an investigation or is \"as-is\"   |\n| ✅ **Implemented** | A change was made on this branch and verified (Decision + commit link)   |\n| ? **Closed**      | Won't fix — with a mandatory one-line reason                             |\n| ? **Tracked**     | Deferred to a repo issue (linked); dropped from the active priority list |\n\n**Inline markers**\n\n| Marker            | Meaning                                                 |\n| ----------------- | ------------------------------------------------------- |\n| ⚠️ **Flag**       | Confirmed gap or bug                                    |\n| ? **Suggestion** | A design\u002Fwording recommendation to react to             |\n| ? **Answered**   | A \"how does this work?\" question answered from the code |\n\n---\n\n## Conventions\n\n- **Terminology:** \"DocumentDB\" for the service; \"MongoDB API\" \u002F \"DocumentDB API\" for the\n  wire protocol. Never \"MongoDB\" alone.\n- **File references:** link the exact file (and line where useful) that produces each\n  behavior so a later implementation pass does not have to re-derive it.\n- **Recommendations are suggestions, not decisions.** The operator (author) owns the call;\n  record their reasoning inline. This is what lets future maintainers understand _why_.\n- **Reconcile after merge.** A running log goes stale the moment behavior changes. When the\n  work merges, stamp the log with a note pointing to the current source of truth (user\n  manual \u002F pre-merge code review).\n","# UX PR Review (agent-assisted)\n\nA UX review is different from a code review: the value comes from **actually using the\nextension and walking real user journeys**, not from reading a diff. The pattern is a\n**person paired with an agent** — the person drives the UX and reports what they see; the\nagent reads the code, verifies each claim against it, keeps the running log, and maintains\nthe todo list.\n\nThis skill has **two modes**:\n\n1. **Prepare (pre-assessment)** — triggered up front. The agent inventories the feature's\n   user interactions, draws where each flow **starts and terminates**, pre-discovers\n   **flow inconsistencies** (modal vs. non-modal vs. silent), seeds the review document,\n   and hands off to the operator with an executive summary.\n2. **Live review** — the operator exercises the feature and dictates observations; the\n   agent verifies against code, records each finding, and keeps the priority index + todo\n   list current.\n\n> The full document skeleton lives in [references\u002Freview-document-template.md](.\u002Freferences\u002Freview-document-template.md).\n> The pre-discovery checklist lives in [references\u002Finconsistency-checklist.md](.\u002Freferences\u002Finconsistency-checklist.md).\n> Worked examples: [`docs\u002Fai-and-plans\u002Ffeatures\u002Fkubernetes-discovery\u002Fiterations\u002F01-kubernetes-discovery\u002Fbugbash-090-ux-review.md`](..\u002F..\u002F..\u002Fdocs\u002Fai-and-plans\u002Ffeatures\u002Fkubernetes-discovery\u002Fiterations\u002F01-kubernetes-discovery\u002Fbugbash-090-ux-review.md) and [`docs\u002Fai-and-plans\u002Ffeatures\u002Findex-management\u002Fiterations\u002F01-index-dashboard\u002Fux-review-iteration-1-2.md`](..\u002F..\u002F..\u002Fdocs\u002Fai-and-plans\u002Ffeatures\u002Findex-management\u002Fiterations\u002F01-index-dashboard\u002Fux-review-iteration-1-2.md).\n\n## When to Use\n\n- The operator asks to **prepare** a UX review, or says they are about to start one.\n- Reviewing the UX\u002Fworkflow of a PR, branch, or feature by hand.\n- Pairing live: the operator reports what they saw and asks you to investigate and update\n  the todo list \u002F review doc.\n\n---\n\n## Mode 1 — Prepare (do this when asked to \"prepare\")\n\nWork through these steps, then stop and hand off. **Do not start critiquing individual\npixels yet** — the goal is to give the operator a seeded document and a map of the flows.\n\n### Step 1 — Identify the review target\n\nDetermine the PR number, branch, and the **feature surface** (the source folders that\nimplement it). If not given, ask which PR\u002Fbranch. Read `package.json` menus\u002Fcommands, the\ntree items, the webview components, and the command handlers for that surface.\n\n### Step 2 — Inventory the user interactions\n\nList every place the user can **act** on this feature: tree nodes and their context menus,\nempty-state rows, wizard steps \u002F quick picks, webview buttons, commands, drag-and-drop.\nFor each, note the **entry point** (how the user gets there) and the **terminal state**\n(success, error, silent no-op, dialog, tree refresh, new panel).\n\n### Step 3 — Draw where flows start and terminate\n\nProduce a **Mermaid `flowchart`** in the document's \"User interaction map\" section: nodes\nfor each user action\u002Fstate, edges for transitions, and **explicit terminal nodes** for\nevery outcome (success toast, modal error, silent no-op, tree badge). Mark inconsistent\nterminations so they stand out.\n\n```mermaid\nflowchart TD\n    A[User clicks 'Start'] --> B{Container ours & alive?}\n    B -- yes --> C[Starting… → Running badge]\n    B -- missing --> D([SILENT no-op ⚠️ only output channel])\n    B -- not ours --> E([Modal warning])\n```\n\nThe point of the diagram is to make **asymmetric terminations obvious**: if one branch\nends in a modal, another in a passive tree row, and a third in nothing at all, the diagram\nshould show it at a glance.\n\n### Step 4 — Pre-discover flow inconsistencies\n\nBefore the operator touches the feature, sweep the code for the inconsistencies UX reviews\nmost often catch (full list in [references\u002Finconsistency-checklist.md](.\u002Freferences\u002Finconsistency-checklist.md)).\nThe headline one:\n\n> **Error\u002Ffeedback surface inconsistency** — the same _class_ of event is surfaced three\n> different ways across the feature: sometimes a **modal** (`showErrorMessage(…, { modal: true })`),\n> sometimes a **non-modal** toast\u002Fwarning, sometimes a **passive tree row**, and sometimes\n> **nothing at all** (a silent early-return with only output-channel text). List every\n> occurrence with its file reference and flag the divergences. The house style across\n> shipped discovery providers is: **errors → modal + output channel; tree rows → actions\n> only; a single canonical \"Click here to retry\" node.**\n\nSeed these as **Flag** items in the document so the operator can confirm them live.\n\n### Step 5 — Seed the review document\n\nCreate the file at **`docs\u002Fai-and-plans\u002Ffeatures\u002F{feature}\u002Fiterations\u002FNN-{slug}.md`** (or\n`...\u002Fiterations\u002FNN-{slug}\u002Fux-review.md` when that iteration already holds several documents).\nPick the feature from the index in\n[`docs\u002Fai-and-plans\u002FREADME.md`](..\u002F..\u002F..\u002Fdocs\u002Fai-and-plans\u002FREADME.md); create a new feature folder\nwith a README if none fits. Use the full skeleton in\n[references\u002Freview-document-template.md](.\u002Freferences\u002Freview-document-template.md):\nheader block, \"How this review was run\", the **Legend** (Priority + Status + Markers), the\n**User interaction map** (the diagram from Step 3), \"The story in one paragraph\", the\n**Priority index** table, the P0→P3 + Implemented section stubs (pre-filled with the Step-4\nFlags as `? Open`), an **Open ideas** section, and an **Appendix** for the flow reference.\n\n> This document is committed. `docs\u002Fai-and-plans\u002F` is tracked — do **not** place it in\n> `docs\u002Fplan\u002F` or `docs\u002Fanalysis\u002F` (those are git-ignored). Never `git add -f`.\n\n### Step 6 — Executive summary + hand-off\n\nEnd your turn with a short **executive summary of the pre-assessment**:\n\n- the feature surface and the flows you mapped;\n- how many pre-discovered Flags you seeded, grouped by suspected severity;\n- the top inconsistencies to confirm (especially error-surface asymmetry);\n- **where the seeded file is**, and an explicit invitation: _\"The pre-seeded review doc is\n  at `\u003Cpath>`. Start the hands-on investigation — exercise the feature and tell me what you\n  see; I'll verify each observation against the code and keep the doc and todo list\n  updated.\"_\n\nDo not proceed to deep per-item analysis until the operator starts driving.\n\n---\n\n## Mode 2 — Live review loop\n\nFor each observation the operator reports:\n\n1. **Verify against code.** Trace the exact code path that produces the behavior. Never\n   record a finding you have not confirmed in the source.\n2. **Record the item** in the correct priority section using the four-part shape:\n   - **Observation** — what the reviewer saw (their words).\n   - **Finding** — what the code does and why, with file references and `⚠️`\u002F`?` markers.\n   - **Suggestion** (?) — the recommended direction. If the operator has a lean, capture it\n     as a blockquote _\"TN leans towards … because …\"_ and keep the status **Open** (it is a\n     suggestion, not a decision).\n   - **Status** — ? Open \u002F ? Open (soft) \u002F ✅ Implemented.\n3. **Update the Priority index** table and the **todo list** (`manage_todo_list`) so the\n   operator always sees remaining items at a glance.\n4. **Heavy trade-offs → Open ideas.** When a finding has real design options, add an\n   `O#` entry with a **pros\u002Fcons table** and a suggested option rather than deciding inline.\n5. **Out-of-scope → issues.** If a finding is beyond the PR's scope or would risk delaying\n   the merge, offer to file a repo issue and link it from the log instead of expanding scope.\n6. **Phase the work.** Review one user journey at a time (first-run\u002Fempty state → adding →\n   presentation → connectivity → destructive actions), closing each out before the next, so\n   context stays lean.\n\nIf the operator asks for tests to lock in an agreed behavior, add them as the finding lands.\n\n---\n\n## Mode 3 — Fixing in iterations\n\nOnce the operator starts choosing fixes, the review runs in **iterations**. Each iteration\nis a numbered pass over the open items; anything **not resolved in an iteration is carried\nforward to the next one** so nothing is ever silently dropped. The document is the ledger:\nan item leaves it only by becoming **Implemented**, **Closed** (won't-fix, with a reason),\nor **filed as a repo issue** (with a link).\n\n### The iteration loop\n\n1. **Group the current iteration.** Under an `## Iteration N` heading (or per-item\n   `➡️ Iteration N` sub-entries, as the K8s review does), list the items being worked this\n   pass. Everything still `? Open` after the pass rolls into `## Iteration N+1`.\n2. **Capture the decision — and its _reason_ — before coding.** When the operator picks a\n   fix, **ask them why**. Record their choice _and_ the reasoning inline on the item as a\n   **Decision** block:\n\n   > **Decision (Iteration N):** {{what was chosen}}. **Reason:** {{operator's rationale}}.\n\n   > **Remind the operator:** _\"This reasoning is the real value of the review — it's what\n   > lets future maintainers and contributors understand **why** the code looks the way it\n   > does. A one-line 'because …' now saves a re-litigation later.\"_ Never invent a\n   > rationale; if the operator hasn't given one, ask for it and wait.\n\n3. **Implement one item at a time.** Follow the code-review discipline in\n   [CONTRIBUTING.md](..\u002F..\u002F..\u002FCONTRIBUTING.md) §6.3: report progress inline; if you deviate\n   from the plan, document why; only proceed when confidence is high, otherwise stop and ask.\n   **Commit each item individually — no mass commits.**\n4. **Document the fix with a commit reference.** After the item is committed, flip its status\n   to `✅ Implemented` and append an **Implemented** block that says what changed, the files\n   touched, and a **link to the commit**:\n\n   > ✅ **Implemented (Iteration N):** {{what was done}}. Files: {{links}}.\n   > Commit: [`{{short-sha}}`]({{commit url}}). Verified via {{lint \u002F tests \u002F build}}.\n\n   If the fix answers a Copilot-reviewer comment or a repo issue, post the same summary there\n   and link it back from the item.\n\n5. **Carry forward the remainder.** At the end of the iteration, update the **Priority\n   index** (status column) and the **todo list** so every unresolved item is explicitly\n   parked in the next iteration. An item is never removed from the ledger without a terminal\n   status.\n\n### Terminal states for an item\n\n| Outcome                 | How it's recorded                                                            |\n| ----------------------- | ---------------------------------------------------------------------------- |\n| Fixed on this branch    | `✅ Implemented` + Decision block + Implemented block with commit link       |\n| Won't fix               | `? Closed` + a one-line **reason** (this reason is mandatory)               |\n| Deferred \u002F out-of-scope | Filed as a repo issue, `? Tracked` + issue link; removed from active P-list |\n| Still open              | Stays `? Open` and **moves to the next iteration**                          |\n\n### After merge\n\nStamp the log with a short reconciliation note pointing to the current source of truth (user\nmanual \u002F pre-merge code review), so a stale iteration is never mistaken for current behavior.\n\n---\n\n## Severity & status legend (use exactly these)\n\n**Priority**\n\n| Priority | Meaning                                            |\n| -------- | -------------------------------------------------- |\n| **P0**   | Blocking — the user gets stuck                     |\n| **P1**   | Broken \u002F misleading, or a consistency & safety gap |\n| **P2**   | Polish, expectation, or a smaller feature gap      |\n| **P3**   | Nice-to-have \u002F cosmetic \u002F acknowledged             |\n\n**Status**\n\n| Status             | Meaning                                                                  |\n| ------------------ | ------------------------------------------------------------------------ |\n| ? **Open**        | Recorded + analyzed; carries a recommendation but stays a _suggestion_   |\n| ? **Open (soft)** | Open, but the recommendation depends on an investigation or is \"as-is\"   |\n| ✅ **Implemented** | A change was made on this branch and verified (Decision + commit link)   |\n| ? **Closed**      | Won't fix — with a mandatory one-line reason                             |\n| ? **Tracked**     | Deferred to a repo issue (linked); dropped from the active priority list |\n\n**Inline markers**\n\n| Marker            | Meaning                                                 |\n| ----------------- | ------------------------------------------------------- |\n| ⚠️ **Flag**       | Confirmed gap or bug                                    |\n| ? **Suggestion** | A design\u002Fwording recommendation to react to             |\n| ? **Answered**   | A \"how does this work?\" question answered from the code |\n\n---\n\n## Conventions\n\n- **Terminology:** \"DocumentDB\" for the service; \"MongoDB API\" \u002F \"DocumentDB API\" for the\n  wire protocol. Never \"MongoDB\" alone.\n- **File references:** link the exact file (and line where useful) that produces each\n  behavior so a later implementation pass does not have to re-derive it.\n- **Recommendations are suggestions, not decisions.** The operator (author) owns the call;\n  record their reasoning inline. This is what lets future maintainers understand _why_.\n- **Reconcile after merge.** A running log goes stale the moment behavior changes. When the\n  work merges, stamp the log with a note pointing to the current source of truth (user\n  manual \u002F pre-merge code review).\n",{"name":5,"description":7},"main","e15fa6c12e64ad9483e1211805956043ce91720d",".github\u002Fskills\u002Fux-pr-review",22,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-13 03:12:30",{"source":8,"skillName":5,"commands":65,"prompt":75,"zipAvailable":76},[66,69,72],{"tool":67,"command":68},"npx","npx skills add microsoft\u002Fvscode-documentdb --skill ux-pr-review",{"tool":70,"command":71},"bunx","bunx skills add microsoft\u002Fvscode-documentdb --skill ux-pr-review",{"tool":73,"command":74},"pnpm","pnpm dlx skills add microsoft\u002Fvscode-documentdb --skill ux-pr-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fux-pr-review\u002FSKILL.md",true,[78,84],{"path":79,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Finconsistency-checklist.md","REFERENCE","参考文档",7808,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fux-pr-review\u002Freferences\u002Finconsistency-checklist.md",{"path":85,"resourceType":80,"resourceTypeDesc":81,"sizeBytes":86,"sourceHtmlUrl":87},"references\u002Freview-document-template.md",9144,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fux-pr-review\u002Freferences\u002Freview-document-template.md",[89,124,147,175,194,214],{"skillNo":90,"name":91,"nameZh":6,"description":92,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":93,"categories":94,"keywords":101,"publishedAt":50},"01M69BSZH60F9JW3N87ZBSKTW8","writing-release-notes","Generates release notes and changelog entries for the DocumentDB extension for Visual Studio Code, and announces releases on GitHub Discussions. Use when preparing version releases, creating patch update notes, writing changelog entries, documenting new features and fixes, or posting a release or patch release announcement to Discussions. Handles both major\u002Fminor versions (new file) and patch updates (append to existing file).","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fwriting-release-notes\u002FSKILL.md",[95,98],{"categoryNo":96,"categoryName":97,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000018","写作与文案",{"categoryNo":99,"categoryName":100,"taxonomyType":26,"taxonomyTypeDesc":27},"01JBSEEDCAT000000000000036","内容创作者",[102,103,104,105,106,107,108,109,110,111,112,35,113,114,115,116,117,118,119,120,121,122,123],"notes","release","release notes","writing","writing release notes","github","update","visual studio code","visual studio","code","new","updates","studio","patch","changelog","announcement","release announcement","releases","features","append","posting","fixes",{"skillNo":125,"name":126,"nameZh":6,"description":127,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":128,"categories":129,"keywords":130,"publishedAt":50},"01M69BSXPVQWSQVYNT6QK38VN1","webview-trpc-messaging","Implements tRPC-based communication between VS Code extension host and React webviews. Use when creating new webview procedures (queries, mutations, subscriptions), adding a new webview router, wiring up a webview controller, using the tRPC client from React components, applying telemetry middleware (telemetryMiddlewareBody), or supporting AbortSignal-based cancellation in webview operations.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fwebview-trpc-messaging\u002FSKILL.md",[],[131,132,133,134,111,135,136,137,138,139,112,140,41,35,141,142,143,144,145,146],"webview trpc messaging","messaging","trpc","telemetry","components","react","react components","middleware","up","host","wiring","router","queries","controller","mutations","communication",{"skillNo":148,"name":149,"nameZh":6,"description":150,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":151,"categories":152,"keywords":153,"publishedAt":50},"01M69BSRV752CSC1NBMFWDCKB5","tree-cluster-architecture","Patterns for cluster nodes and tree data providers in vscode-documentdb. Use when adding or changing a cluster tree item, discovery provider, Connections\u002FAzure\u002FDiscovery tree hierarchy, tree\u002Flist mode, cluster identity, treeId\u002FclusterId lookup, Collection View import\u002Fexport resolution, reveal behavior, credentials, shell actions, or copy connection string support.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Ftree-cluster-architecture\u002FSKILL.md",[],[154,155,156,157,158,159,160,161,162,163,35,164,165,166,167,168,169,170,171,172,173,174],"tree cluster architecture","architecture","tree","cluster","azure","support","vscode","identity","actions","mode","collection","hierarchy","credentials","reveal","export","data","list","patterns","Providers","STRING","import",{"skillNo":176,"name":177,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":181,"publishedAt":50},"01M69BSPMFSH3FAR4R5TGDB468","telemetry-instrumentation","Instrumentation patterns for telemetry in the vscode-documentdb extension. Use when adding telemetry to a feature, enriching existing telemetry with properties or measurements, linking related events with correlation IDs, instrumenting commands or tree views, suppressing noisy events, or deciding what data points to capture. Also use when asked to \"add telemetry\" or \"improve telemetry\" for any feature.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Ftelemetry-instrumentation\u002FSKILL.md",[],[182,134,183,160,184,185,35,186,187,169,171,188,189,156,190,37,41,191,192,193],"telemetry instrumentation","instrumentation","ids","improve","linking","commands","add","events","feature","Existing","with","properties",{"skillNo":195,"name":196,"nameZh":6,"description":197,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":198,"categories":199,"keywords":201,"publishedAt":50},"01M69BSMRAT64W6F3F15FVQ9QK","skill-creator","Guide for creating effective GitHub Copilot skills (.github\u002Fskills\u002F) in this repository. Use when creating a new skill, updating an existing skill, or when asked about skill structure, format, or best practices for the vscode-documentdb project.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Fskill-creator\u002FSKILL.md",[200],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},[202,203,204,107,205,160,206,37,207,112,41,191,35,208,209,210,38,211,212,213],"skill creator","creator","github copilot","best practices","copilot","project","structure","github copilot skills","copilot skills","format","repository","new skill",{"skillNo":215,"name":216,"nameZh":6,"description":217,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":218,"categories":219,"keywords":220,"publishedAt":50},"01M69BSJZA3VPPP4XMY7G2QA6V","review-external-pr","Triage an external contributor's PR and prepare it for merge. Detects push permission, base branch, draft state, size, and history quality, then picks one of three paths (review-only, direct push to contributor branch, or a `reviews\u002F` staging branch). Use when triaging or reviewing a community PR, deciding whether maintainer changes are needed, choosing a merge strategy (squash\u002Fmerge\u002Frebase), or merging an external contribution.","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fvscode-documentdb\u002Fblob\u002Fmain\u002F.github\u002Fskills\u002Freview-external-pr\u002FSKILL.md",[],[30,221,33,222,48,223,224,225,226,227,228,35,229,230,231,232,233,234,235,236,37,237],"review external pr","triage","merge","community","reviews","branch","only","contributor","paths","permission","rebase","direct","push","history","three","squash","strategy"]