[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M699FGTNTK2KD0XV1BERDX3Z":3,"skill-same:01M699FGTNTK2KD0XV1BERDX3Z":100},{"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":18,"publishedAt":43,"linkOnly":44,"markdownContent":45,"markdownBody":46,"frontMatter":47,"refName":48,"commitSha":49,"skillDirectory":50,"forksCount":51,"repositoryHtmlUrl":52,"repositoryHomepageUrl":53,"ownerHtmlUrl":54,"ownerBlogUrl":55,"ownerDescription":56,"updatedAt":57,"install":58,"resources":71},"01M699FGTNTK2KD0XV1BERDX3Z","docs-sync",null,"Use this skill whenever a pull request is opened, reopened, or synchronized in microsoft\u002Fapm to assess whether and how the documentation corpus must change to stay truthful with the proposed code change. Activate even when the PR title or body says nothing about docs -- the skill must run on every PR to detect silent drift between code and docs. Classifies impact as no-change, in-place edit (one to a few paragraphs), or structural change (new page or TOC reshape), then orchestrates a CDO + doc-writer + python-architect + editorial-owner + growth-hacker loop to produce a patch-ready advisory. Does NOT review code quality, security, or test coverage. Does NOT auto-merge or auto-push doc edits.","microsoft\u002Fapm","microsoft","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F6154722?v=4","01M698VYDXZ6JW5WH3CRV650R8","Microsoft","01M699CC41JR5QW38C9PDX6101",4361,"MIT","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,9,40,41,42],"docs","sync","docs sync","when","review","hacker","impact","structural","drift","writer","pr title","activate","patch","ready","auto","coverage","loop","code","documentation","merge","change","test","security","python","2026-11-10 10:12:30",false,"---\nname: docs-sync\ndescription: >-\n  Use this skill whenever a pull request is opened, reopened, or\n  synchronized in microsoft\u002Fapm to assess whether and how the\n  documentation corpus must change to stay truthful with the\n  proposed code change. Activate even when the PR title or body\n  says nothing about docs -- the skill must run on every PR to\n  detect silent drift between code and docs. Classifies impact\n  as no-change, in-place edit (one to a few paragraphs), or\n  structural change (new page or TOC reshape), then orchestrates\n  a CDO + doc-writer + python-architect + editorial-owner +\n  growth-hacker loop to produce a patch-ready advisory. Does NOT\n  review code quality, security, or test coverage. Does NOT\n  auto-merge or auto-push doc edits.\n---\n\n# docs-sync -- per-PR documentation impact panel\n\nThe docs corpus drifts silently and constantly. This skill catches\ndrift at PR-open time, classifies its impact, and orchestrates a\npersona panel to produce a patch-ready advisory comment.\n\nThe pattern is **A1 PANEL + B1 FAN-OUT\u002FSYNTHESIZER + A8 ALIGNMENT\nLOOP**. The classifier is the cost gate (~70% of PRs short-circuit\nto no-change with ~1 LLM call). When the panel does fan out, every\nagent reads a bounded context (~10 KB) -- never the full corpus.\n\nThis skill is ADVISORY. It does not gate merge, apply verdict\nlabels, or push to the contributor's fork. The orchestrator is the\nsole writer to the PR: exactly one comment per run (idempotent\nedit-in-place), plus optional label sweeps.\n\n## Architecture invariants\n\n- **Cost ceiling: 15 LLM calls per run.** Hard-wired. The orchestrator refuses to spawn beyond. Header prints `N\u002F15` for observability.\n- **Single-writer interlock.** Only the orchestrator writes. Panelist subagents return JSON; they MUST NOT call any `gh` write command, post comments, or touch PR state.\n- **Idempotent comment.** Exactly one comment per run, with a stable header `## Docs sync advisory`. Re-runs edit-in-place using `gh pr comment --edit-last`.\n- **No fork-write.** Companion docs PRs require Step 7's fresh responsible-human issue-scope checkpoint and open in the BASE repo; never pushed to the contributor's fork. Labels request advice, not implementation.\n- **Index-not-corpus reads.** Every classifier and architect agent reads `.apm\u002Fdocs-index.yml`, NOT the corpus itself. The corpus is sampled only by the localizer (which reads the specific candidate pages) and by per-page panelists (which read one page each).\n- **S7 deterministic tool bridge.** The python-architect panelist MUST run real `apm --help`, `grep`, and `python -c` commands to verify doc claims, never assert from prose.\n\n## Roster\n\n| Role | Agent | Always active? |\n|---|---|---|\n| Classifier | [doc-analyser](..\u002F..\u002Fagents\u002Fdoc-analyser.agent.md) inside [docs-impact-classifier](..\u002Fdocs-impact-classifier\u002FSKILL.md) | Yes (every run) |\n| Localizer | [docs-impact-localizer](..\u002Fdocs-impact-localizer\u002FSKILL.md) | Only on `in_place` verdict |\n| Architect | [docs-impact-architect](..\u002Fdocs-impact-architect\u002FSKILL.md) | Only on `structural` verdict |\n| Writer | [doc-writer](..\u002F..\u002Fagents\u002Fdoc-writer.agent.md) | Per candidate page (fan-out) |\n| Verifier | [python-architect](..\u002F..\u002Fagents\u002Fpython-architect.agent.md) | Per candidate page (fan-out, S7) |\n| Editorial | [editorial-owner](..\u002F..\u002Fagents\u002Feditorial-owner.agent.md) | Once across all redrafts |\n| Growth | [oss-growth-hacker](..\u002F..\u002Fagents\u002Foss-growth-hacker.agent.md) | Once across all redrafts |\n| Synthesizer | [cdo](..\u002F..\u002Fagents\u002Fcdo.agent.md) | Once, with ALIGNMENT LOOP up to 3 redrafts |\n\n## Topology\n\n```\n   docs-sync SKILL (orchestrator thread)\n                 |\n   Step 1: classify (1 LLM call, may exit here)\n                 |\n                 v\n            verdict?\n            \u002F    |    \\\n   no-change  in-place  structural\n       |        |          |\n     EXIT       |       architect (TOC delta)\n                |          |\n                +----\u003C-----+\n                |\n   Step 2: localize (1 LLM call) -- per-page task brief\n                |\n   Step 3: FAN-OUT panel via task tool\n                |\n       +----+----+----+----+\n       v    v    v    v    v\n     writer  verify edit growth\n     x N    x N   once  once\n       (parallel; each \u003C=10 KB context)\n                |\n   Step 4: schema-validate returns\n                |\n   Step 5: CDO synthesize (1 LLM call)\n                |\n            agree?\n            \u002F | \\\n        revise (N\u003C=3 redrafts) | agree\n                                  |\n   Step 6: emit ONE comment via safe-outputs.add-comment\n   Step 7: OPTIONAL companion docs PR (structural AND fresh\n           responsible-human issue-scope checkpoint)\n```\n\n## Execution checklist\n\n### Step 1 -- Classify\n\nSpawn ONE task: load the `docs-impact-classifier` skill, pass it the\nPR number. It returns the classifier JSON.\n\nValidate the JSON against `assets\u002Fclassifier-return-schema.json`.\nOn schema failure, abort the run with a comment explaining the\ninternal error.\n\nIf verdict is `no_change`: skip to Step 6 with a brief advisory\n(\"No docs impact detected. Reason: \u003Cone-line>. LLM calls: 1\u002F15.\")\n\n### Step 2 -- Localize (in_place) or Architect (structural)\n\nFor `in_place`: spawn ONE task that loads the\n`docs-impact-localizer` skill with the classifier output. Returns\nper-page task briefs.\n\nFor `structural`: spawn ONE task that loads the\n`docs-impact-architect` skill with the classifier output. Returns\nTOC delta + new-page outlines + downstream in-place pages. THEN\nspawn the localizer for those downstream pages.\n\n### Step 3 -- Fan-out panel\n\n**Cascade-size mitigation (PR 1244 class).** If `scope_pages[]` has\n>8 entries, the per-page fan-out at one writer call per page would\napproach the 15-call ceiling with no headroom for verifier redrafts.\nBEFORE spawning, group `scope_pages[]` into SECTIONS:\n\n- Pages under the same TOC section (e.g. all `consumer\u002F**`) with the\n  SAME conceptual fix (e.g. \"rename apm update -> apm self-update in\n  every mention\") become ONE writer task with a `pages_in_section[]`\n  array in its brief.\n- A 9-page rename cascade collapses to 2-3 section writer tasks.\n\nThe python-architect verifier still runs per `verify_claims[]` (not\nper page), because S7 evidence is keyed on claims, not pages.\n\nFor each page-or-section in the per-page task brief, spawn TWO parallel tasks:\n\n1. **doc-writer** task -- drafts the patch for that page's (or section's) specific edits. Output: JSON with `before:`, `after:` for each location.\n2. **python-architect** task -- for each `verify_claims[]` in the page brief, run the actual command (S7 tool bridge: `apm \u003Cverb> --help`, `grep -n \u003Csymbol> src\u002F`). Output: JSON with `claim: verified | refuted | inconclusive` per claim.\n\nIn parallel with the per-page fan-out, spawn ONCE each:\n\n3. **editorial-owner** task -- receives ALL writer drafts, returns tone fixes.\n4. **oss-growth-hacker** task -- receives ALL writer drafts, returns ramp-clarity notes (does this read well to a cold OSS visitor).\n\nAll panelist tasks return JSON matching `assets\u002Fpanelist-return-schema.json`.\nSchema-validate every return; on failure, abort.\n\n### Step 4 -- Validate\n\nCross-check:\n\n- Every `verify_claims` from a python-architect comes back `verified` or `inconclusive` (never `refuted`). If any are `refuted`, the doc-writer's draft is wrong; re-run the writer for that page with the refutation as context.\n- Cross-page constraints from the localizer are honored across all writer drafts.\n- All drafts are ASCII-only (per repo encoding rule).\n\n### Step 5 -- CDO synthesize\n\nSpawn ONE task: load the `cdo` persona with the full panel return\n(writer drafts + verifier reports + editorial notes + growth notes\n+ classifier verdict + (architect output if structural)) and\n`.apm\u002Fdocs-index.yml`.\n\nThe CDO returns one of three verdicts:\n\n- `agree`: ship. Proceed to Step 6.\n- `revise`: re-spawn the writer panelists with the CDO's specific\n  concerns as additional context. Re-run the editorial and growth\n  passes if needed. Bounded N \u003C= 3 redrafts. Increment a redraft\n  counter; if it hits 3 and CDO still disagrees, ship with\n  `cdo_disagreement_noted: true`.\n- `ship_with_disagreement`: ship as-is with the disagreement\n  surfaced in the comment for the maintainer to weigh.\n\n### Step 6 -- Emit ONE comment\n\nRender `assets\u002Fadvisory-comment-template.md` with the final results.\nWrite it via `safe-outputs.add-comment`. Header is exactly\n`## Docs sync advisory` (stable for idempotent edit-in-place).\n\nThe comment MUST include the cost header:\n\n```\nVerdict: \u003Cverdict>  *  Pages affected: N  *  LLM calls: M\u002F15  *  Took: Xs\n```\n\n### Step 7 -- Optional companion PR\n\nOnly on `structural` verdict in a human-supervised follow-up.\n`docs-sync-confirm` is at most a request to discuss the proposal; it\nnever ratifies scope or permits companion implementation. This applies\neven when an older workflow prompt calls it confirmation. Unattended\nlabel\u002Fmanual-dispatch runs end with advice, not a companion PR.\n\nBefore editing, tie the companion to a real issue and a nominated\nscope-record comment URL. In a trusted default-branch checkout of the\ntarget repository (not the contributor branch or skill directory), probe:\n\n```bash\nnode scripts\u002Fgovernance\u002Feligibility.cjs --help\nnode scripts\u002Fgovernance\u002Feligibility.cjs --repo microsoft\u002Fapm --issue N --approval-url URL\n```\n\nThe target's `authority.cjs` owns record interpretation and the trusted\nGOVERNANCE.md roster. Do not add a package dependency, duplicate parser,\nor label-based roster. Missing tool, incomplete\u002FAPI-failed reads, or\nunverifiable evidence means STOP and escalate.\n\nThe result always has `authorizes_implementation: false`: even an\nunedited scope evidence record cannot reveal deleted withdrawals.\nObtain a fresh explicit confirmation from a responsible human for this\nissue's bounded scope, done-when, exclusions, and review contact before\ncompanion implementation. Capture its current confirmation reference;\nneither bot advice, a review, historical acceptance, silence, nor a label\nis consent. A named contact is not proof of review availability.\n\nOnly after that checkpoint:\n\n1. Branch name: `docs-sync\u002Fcompanion-\u003CPR_NUMBER>` in the BASE repo.\n2. Apply the doc-writer drafts as a commit on that branch.\n3. Apply the architect's TOC delta (`.apm\u002Fdocs-index.yml` entries +\n   new page files + redirects on retired pages).\n4. Open a draft PR linked to the original PR, with the advisory\n   comment text as the PR body.\n5. Reference the companion PR in the advisory comment.\n\nThe default is to recommend patches without opening a PR. Reconfirm on\nresume, changed scope, or uncertain withdrawal; never auto-push or merge.\n\n## Cost accounting\n\nThe orchestrator maintains a running LLM-call counter:\n\n| Step | Min calls | Max calls |\n|---|---|---|\n| Step 1 classify | 1 | 1 |\n| Step 2 localize\u002Farchitect | 0 | 2 |\n| Step 3 fan-out (N pages) | 0 | 2N + 2 |\n| Step 5 CDO | 0 | 1 + 3 redrafts |\n| Total | 1 | 15 |\n\nIf the counter would exceed 15, the orchestrator stops spawning,\nships the partial result with `cost_ceiling_hit: true`, and the\ncomment surfaces the truncation.\n\n## Anti-patterns\n\n- Reading the corpus instead of the index. Context budget breach.\n- Letting panelists post comments. Single-writer interlock violation.\n- Ignoring `refuted` verify_claims. That's silent drift you're shipping.\n- Skipping the CDO synthesis on \"obvious\" in-place patches. The bridges still matter.\n- Treating `docs-sync-confirm` or evidence JSON as ratification. Only the fresh responsible-human issue-scope checkpoint permits implementation.\n- Re-running on every push (synchronize). Wasteful. Re-apply the trigger label for re-run.\n\n## Operating modes\n\n- **Rung 1 (label-gated, default)**: triggered by `docs-sync` label on PR. Maintainer opts in.\n- **Rung 2 (default-on)**: triggered on every `pull_request_target` event. Enabled only after shadow validation.\n\nThe workflow file controls which rung is active. The skill body is\nidentical for both.\n","# docs-sync -- per-PR documentation impact panel\n\nThe docs corpus drifts silently and constantly. This skill catches\ndrift at PR-open time, classifies its impact, and orchestrates a\npersona panel to produce a patch-ready advisory comment.\n\nThe pattern is **A1 PANEL + B1 FAN-OUT\u002FSYNTHESIZER + A8 ALIGNMENT\nLOOP**. The classifier is the cost gate (~70% of PRs short-circuit\nto no-change with ~1 LLM call). When the panel does fan out, every\nagent reads a bounded context (~10 KB) -- never the full corpus.\n\nThis skill is ADVISORY. It does not gate merge, apply verdict\nlabels, or push to the contributor's fork. The orchestrator is the\nsole writer to the PR: exactly one comment per run (idempotent\nedit-in-place), plus optional label sweeps.\n\n## Architecture invariants\n\n- **Cost ceiling: 15 LLM calls per run.** Hard-wired. The orchestrator refuses to spawn beyond. Header prints `N\u002F15` for observability.\n- **Single-writer interlock.** Only the orchestrator writes. Panelist subagents return JSON; they MUST NOT call any `gh` write command, post comments, or touch PR state.\n- **Idempotent comment.** Exactly one comment per run, with a stable header `## Docs sync advisory`. Re-runs edit-in-place using `gh pr comment --edit-last`.\n- **No fork-write.** Companion docs PRs require Step 7's fresh responsible-human issue-scope checkpoint and open in the BASE repo; never pushed to the contributor's fork. Labels request advice, not implementation.\n- **Index-not-corpus reads.** Every classifier and architect agent reads `.apm\u002Fdocs-index.yml`, NOT the corpus itself. The corpus is sampled only by the localizer (which reads the specific candidate pages) and by per-page panelists (which read one page each).\n- **S7 deterministic tool bridge.** The python-architect panelist MUST run real `apm --help`, `grep`, and `python -c` commands to verify doc claims, never assert from prose.\n\n## Roster\n\n| Role | Agent | Always active? |\n|---|---|---|\n| Classifier | [doc-analyser](..\u002F..\u002Fagents\u002Fdoc-analyser.agent.md) inside [docs-impact-classifier](..\u002Fdocs-impact-classifier\u002FSKILL.md) | Yes (every run) |\n| Localizer | [docs-impact-localizer](..\u002Fdocs-impact-localizer\u002FSKILL.md) | Only on `in_place` verdict |\n| Architect | [docs-impact-architect](..\u002Fdocs-impact-architect\u002FSKILL.md) | Only on `structural` verdict |\n| Writer | [doc-writer](..\u002F..\u002Fagents\u002Fdoc-writer.agent.md) | Per candidate page (fan-out) |\n| Verifier | [python-architect](..\u002F..\u002Fagents\u002Fpython-architect.agent.md) | Per candidate page (fan-out, S7) |\n| Editorial | [editorial-owner](..\u002F..\u002Fagents\u002Feditorial-owner.agent.md) | Once across all redrafts |\n| Growth | [oss-growth-hacker](..\u002F..\u002Fagents\u002Foss-growth-hacker.agent.md) | Once across all redrafts |\n| Synthesizer | [cdo](..\u002F..\u002Fagents\u002Fcdo.agent.md) | Once, with ALIGNMENT LOOP up to 3 redrafts |\n\n## Topology\n\n```\n   docs-sync SKILL (orchestrator thread)\n                 |\n   Step 1: classify (1 LLM call, may exit here)\n                 |\n                 v\n            verdict?\n            \u002F    |    \\\n   no-change  in-place  structural\n       |        |          |\n     EXIT       |       architect (TOC delta)\n                |          |\n                +----\u003C-----+\n                |\n   Step 2: localize (1 LLM call) -- per-page task brief\n                |\n   Step 3: FAN-OUT panel via task tool\n                |\n       +----+----+----+----+\n       v    v    v    v    v\n     writer  verify edit growth\n     x N    x N   once  once\n       (parallel; each \u003C=10 KB context)\n                |\n   Step 4: schema-validate returns\n                |\n   Step 5: CDO synthesize (1 LLM call)\n                |\n            agree?\n            \u002F | \\\n        revise (N\u003C=3 redrafts) | agree\n                                  |\n   Step 6: emit ONE comment via safe-outputs.add-comment\n   Step 7: OPTIONAL companion docs PR (structural AND fresh\n           responsible-human issue-scope checkpoint)\n```\n\n## Execution checklist\n\n### Step 1 -- Classify\n\nSpawn ONE task: load the `docs-impact-classifier` skill, pass it the\nPR number. It returns the classifier JSON.\n\nValidate the JSON against `assets\u002Fclassifier-return-schema.json`.\nOn schema failure, abort the run with a comment explaining the\ninternal error.\n\nIf verdict is `no_change`: skip to Step 6 with a brief advisory\n(\"No docs impact detected. Reason: \u003Cone-line>. LLM calls: 1\u002F15.\")\n\n### Step 2 -- Localize (in_place) or Architect (structural)\n\nFor `in_place`: spawn ONE task that loads the\n`docs-impact-localizer` skill with the classifier output. Returns\nper-page task briefs.\n\nFor `structural`: spawn ONE task that loads the\n`docs-impact-architect` skill with the classifier output. Returns\nTOC delta + new-page outlines + downstream in-place pages. THEN\nspawn the localizer for those downstream pages.\n\n### Step 3 -- Fan-out panel\n\n**Cascade-size mitigation (PR 1244 class).** If `scope_pages[]` has\n>8 entries, the per-page fan-out at one writer call per page would\napproach the 15-call ceiling with no headroom for verifier redrafts.\nBEFORE spawning, group `scope_pages[]` into SECTIONS:\n\n- Pages under the same TOC section (e.g. all `consumer\u002F**`) with the\n  SAME conceptual fix (e.g. \"rename apm update -> apm self-update in\n  every mention\") become ONE writer task with a `pages_in_section[]`\n  array in its brief.\n- A 9-page rename cascade collapses to 2-3 section writer tasks.\n\nThe python-architect verifier still runs per `verify_claims[]` (not\nper page), because S7 evidence is keyed on claims, not pages.\n\nFor each page-or-section in the per-page task brief, spawn TWO parallel tasks:\n\n1. **doc-writer** task -- drafts the patch for that page's (or section's) specific edits. Output: JSON with `before:`, `after:` for each location.\n2. **python-architect** task -- for each `verify_claims[]` in the page brief, run the actual command (S7 tool bridge: `apm \u003Cverb> --help`, `grep -n \u003Csymbol> src\u002F`). Output: JSON with `claim: verified | refuted | inconclusive` per claim.\n\nIn parallel with the per-page fan-out, spawn ONCE each:\n\n3. **editorial-owner** task -- receives ALL writer drafts, returns tone fixes.\n4. **oss-growth-hacker** task -- receives ALL writer drafts, returns ramp-clarity notes (does this read well to a cold OSS visitor).\n\nAll panelist tasks return JSON matching `assets\u002Fpanelist-return-schema.json`.\nSchema-validate every return; on failure, abort.\n\n### Step 4 -- Validate\n\nCross-check:\n\n- Every `verify_claims` from a python-architect comes back `verified` or `inconclusive` (never `refuted`). If any are `refuted`, the doc-writer's draft is wrong; re-run the writer for that page with the refutation as context.\n- Cross-page constraints from the localizer are honored across all writer drafts.\n- All drafts are ASCII-only (per repo encoding rule).\n\n### Step 5 -- CDO synthesize\n\nSpawn ONE task: load the `cdo` persona with the full panel return\n(writer drafts + verifier reports + editorial notes + growth notes\n+ classifier verdict + (architect output if structural)) and\n`.apm\u002Fdocs-index.yml`.\n\nThe CDO returns one of three verdicts:\n\n- `agree`: ship. Proceed to Step 6.\n- `revise`: re-spawn the writer panelists with the CDO's specific\n  concerns as additional context. Re-run the editorial and growth\n  passes if needed. Bounded N \u003C= 3 redrafts. Increment a redraft\n  counter; if it hits 3 and CDO still disagrees, ship with\n  `cdo_disagreement_noted: true`.\n- `ship_with_disagreement`: ship as-is with the disagreement\n  surfaced in the comment for the maintainer to weigh.\n\n### Step 6 -- Emit ONE comment\n\nRender `assets\u002Fadvisory-comment-template.md` with the final results.\nWrite it via `safe-outputs.add-comment`. Header is exactly\n`## Docs sync advisory` (stable for idempotent edit-in-place).\n\nThe comment MUST include the cost header:\n\n```\nVerdict: \u003Cverdict>  *  Pages affected: N  *  LLM calls: M\u002F15  *  Took: Xs\n```\n\n### Step 7 -- Optional companion PR\n\nOnly on `structural` verdict in a human-supervised follow-up.\n`docs-sync-confirm` is at most a request to discuss the proposal; it\nnever ratifies scope or permits companion implementation. This applies\neven when an older workflow prompt calls it confirmation. Unattended\nlabel\u002Fmanual-dispatch runs end with advice, not a companion PR.\n\nBefore editing, tie the companion to a real issue and a nominated\nscope-record comment URL. In a trusted default-branch checkout of the\ntarget repository (not the contributor branch or skill directory), probe:\n\n```bash\nnode scripts\u002Fgovernance\u002Feligibility.cjs --help\nnode scripts\u002Fgovernance\u002Feligibility.cjs --repo microsoft\u002Fapm --issue N --approval-url URL\n```\n\nThe target's `authority.cjs` owns record interpretation and the trusted\nGOVERNANCE.md roster. Do not add a package dependency, duplicate parser,\nor label-based roster. Missing tool, incomplete\u002FAPI-failed reads, or\nunverifiable evidence means STOP and escalate.\n\nThe result always has `authorizes_implementation: false`: even an\nunedited scope evidence record cannot reveal deleted withdrawals.\nObtain a fresh explicit confirmation from a responsible human for this\nissue's bounded scope, done-when, exclusions, and review contact before\ncompanion implementation. Capture its current confirmation reference;\nneither bot advice, a review, historical acceptance, silence, nor a label\nis consent. A named contact is not proof of review availability.\n\nOnly after that checkpoint:\n\n1. Branch name: `docs-sync\u002Fcompanion-\u003CPR_NUMBER>` in the BASE repo.\n2. Apply the doc-writer drafts as a commit on that branch.\n3. Apply the architect's TOC delta (`.apm\u002Fdocs-index.yml` entries +\n   new page files + redirects on retired pages).\n4. Open a draft PR linked to the original PR, with the advisory\n   comment text as the PR body.\n5. Reference the companion PR in the advisory comment.\n\nThe default is to recommend patches without opening a PR. Reconfirm on\nresume, changed scope, or uncertain withdrawal; never auto-push or merge.\n\n## Cost accounting\n\nThe orchestrator maintains a running LLM-call counter:\n\n| Step | Min calls | Max calls |\n|---|---|---|\n| Step 1 classify | 1 | 1 |\n| Step 2 localize\u002Farchitect | 0 | 2 |\n| Step 3 fan-out (N pages) | 0 | 2N + 2 |\n| Step 5 CDO | 0 | 1 + 3 redrafts |\n| Total | 1 | 15 |\n\nIf the counter would exceed 15, the orchestrator stops spawning,\nships the partial result with `cost_ceiling_hit: true`, and the\ncomment surfaces the truncation.\n\n## Anti-patterns\n\n- Reading the corpus instead of the index. Context budget breach.\n- Letting panelists post comments. Single-writer interlock violation.\n- Ignoring `refuted` verify_claims. That's silent drift you're shipping.\n- Skipping the CDO synthesis on \"obvious\" in-place patches. The bridges still matter.\n- Treating `docs-sync-confirm` or evidence JSON as ratification. Only the fresh responsible-human issue-scope checkpoint permits implementation.\n- Re-running on every push (synchronize). Wasteful. Re-apply the trigger label for re-run.\n\n## Operating modes\n\n- **Rung 1 (label-gated, default)**: triggered by `docs-sync` label on PR. Maintainer opts in.\n- **Rung 2 (default-on)**: triggered on every `pull_request_target` event. Enabled only after shadow validation.\n\nThe workflow file controls which rung is active. The skill body is\nidentical for both.\n",{"name":5,"description":7},"main","2920043258932f0f67e6f01df7b9047eb42f358c",".apm\u002Fskills\u002Fdocs-sync",425,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm","https:\u002F\u002Fmicrosoft.github.io\u002Fapm\u002F","https:\u002F\u002Fgithub.com\u002Fmicrosoft","https:\u002F\u002Fopensource.microsoft.com","Open source projects and samples from Microsoft","2026-11-13 18:27:31",{"source":8,"skillName":5,"commands":59,"prompt":69,"zipAvailable":70},[60,63,66],{"tool":61,"command":62},"npx","npx skills add microsoft\u002Fapm --skill docs-sync",{"tool":64,"command":65},"bunx","bunx skills add microsoft\u002Fapm --skill docs-sync",{"tool":67,"command":68},"pnpm","pnpm dlx skills add microsoft\u002Fapm --skill docs-sync","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002FSKILL.md",true,[72,78,82,86,92,96],{"path":73,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":76,"sourceHtmlUrl":77},"assets\u002Fadvisory-comment-template.md","ASSET","资产文件",2700,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002Fassets\u002Fadvisory-comment-template.md",{"path":79,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":80,"sourceHtmlUrl":81},"assets\u002Fclassifier-return-schema.json",1687,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002Fassets\u002Fclassifier-return-schema.json",{"path":83,"resourceType":74,"resourceTypeDesc":75,"sizeBytes":84,"sourceHtmlUrl":85},"assets\u002Fpanelist-return-schema.json",2164,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002Fassets\u002Fpanelist-return-schema.json",{"path":87,"resourceType":88,"resourceTypeDesc":89,"sizeBytes":90,"sourceHtmlUrl":91},"evals\u002Fcontent-evals.json","REFERENCE","参考文档",4313,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002Fevals\u002Fcontent-evals.json",{"path":93,"resourceType":88,"resourceTypeDesc":89,"sizeBytes":94,"sourceHtmlUrl":95},"evals\u002FREADME.md",1325,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002Fevals\u002FREADME.md",{"path":97,"resourceType":88,"resourceTypeDesc":89,"sizeBytes":98,"sourceHtmlUrl":99},"evals\u002Ftrigger-evals.json",2317,"https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002F.apm\u002Fskills\u002Fdocs-sync\u002Fevals\u002Ftrigger-evals.json",[101,107,113,118,123,128],{"skillNo":102,"name":103,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":104,"categories":105,"keywords":106,"publishedAt":43},"01M699JMZBYWPBT7JYWBSB95Z6","hello","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fshared\u002Fminimal_skill\u002F.apm\u002Fskills\u002Fhello\u002FSKILL.md",[],[103],{"skillNo":108,"name":109,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":110,"categories":111,"keywords":112,"publishedAt":43},"01M699JKAMZ4DH1PYJMXHE4FG4","placeholder","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs25_copilot_alias\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[109],{"skillNo":114,"name":109,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":115,"categories":116,"keywords":117,"publishedAt":43},"01M699JHR9DKJ7BZHAPF6DZX2Z","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs24_priority_override\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[109],{"skillNo":119,"name":109,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":120,"categories":121,"keywords":122,"publishedAt":43},"01M699JG5BJBZSWM25F1VMJ2H6","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs23_error_renderer\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[109],{"skillNo":124,"name":109,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":127,"publishedAt":43},"01M699JEFSMBP3HNS061R15CE9","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs22_gemini_md_only\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[109],{"skillNo":129,"name":109,"nameZh":6,"description":6,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":43},"01M699JCRCJCVZ3Z3RD8F9MXF5","https:\u002F\u002Fgithub.com\u002Fmicrosoft\u002Fapm\u002Fblob\u002Fmain\u002Ftests\u002Fintegration\u002Ffixtures\u002Ftarget_resolution\u002Fs21_codex_dir\u002F.apm\u002Fskills\u002Fplaceholder\u002FSKILL.md",[],[109]]