以下为本文档的中文说明apm-spec-guardianAPM 规范守护者是微软提供的一个面向大型组织内部代码审查场景的专业技能专门用于对任何涉及 APMApplication Performance Management 应用性能管理 / Application Performance Monitoring 应用性能监控规范和配置变更的拉取请求Pull Request / Merge Request执行四面板对抗性咨询审查。在大型企业和复杂的微服务架构中APM 的可观测性基础设施指标 Metrics、链路追踪 Tracing、日志 Logging的一致性和规范性直接关系到运维团队能否在故障发生时快速定位根因。该技能确保每一次 APM 相关的代码变更都经过严格的多视角审查。使用场景包括在代码审查流程中自动识别和标记涉及 APM 配置或埋点代码变更的 Pull Request并触发深入的 APM 专项审查确保新建或修改的监控仪表板、自定义指标Custom Metrics、分布式追踪 Span 定义和日志结构化字段严格遵守团队或组织预先定义的 APM 命名规范、标签规范Tag Convention和采样策略约定在大型组织中保持跨团队的 APM 数据采集和上报实践的一致性和高质量标准防止因各自为政导致的监控数据污染和碎片化。核心特点包括采用独创的四面板对抗性评审方法论Four-Panel / Quadrant-Based Adversarial Review模拟从四个彼此独立且视角互补的专家角色对同一份代码变更进行全方位审视第一面板规范合规性检查 APM 配置是否遵循了组织定义的命名规范如指标名称的 Metric Naming Convention 必须包含服务名模块名指标名三段式、标签属性白名单Allowed Tag Keys和采样率Sampling Rate策略阈值第二面板性能影响评估新增或修改的 APM 数据采集点和埋点逻辑对宿主应用运行时性能的实际影响关注是否存在过度采集、高频采集或串行阻塞的埋点代码模式第三面板安全风险分析 APM 数据上报链路中是否存在意外泄露敏感数据PII、Token、SQL 查询中的用户个人信息的风险检查是否有对采集数据进行脱敏处理Data Masking / Redaction第四面板可维护性评估 APM 配置代码的质量、可读性和团队内其他成员理解和修改的难易程度。APM Spec Guardian – Four-Panel Advisory Review for OpenAPMThis skill institutionalizes the two-round adversarial spec reviewthat produced OpenAPM v0.1 by hand. The panel is FAN-OUT SYNTHESIZER. Each panelist runs in its own agent thread (via thetasktool) and returns JSON matchingassets/panelist-return-schema.json. The orchestrator schema-validateseach return, hands all returns to thespec-editor-synthesizer(also a task thread, returns JSON matchingassets/synthesizer-return-schema.json), runs the linter checklistinassets/linter-checklist.md, then renders ONE comment fromassets/comment-template.md.This skill is ADVISORY by design. It does not compute a binaryverdict, it does not apply verdict labels, and it does not gatemerge. The panel surfaces findings; the maintainer ships.Activation scopeThis skill activates ONLY when the PR diff touches at least one of:docs/src/content/docs/specs/openapm-*.md(the normative specartifact, current and future versions)docs/src/content/docs/specs/schemas/*.schema.json(sidecar JSONSchemas, if/when the inline Appendix-A schemas are extracted tofiles)tests/fixtures/spec-conformance/**(the conformance fixture seed)Edits to any OTHER documentation page MUST NOT trigger this skill.The maintainer’s generaldocs-syncskill covers those.Architecture invariantsAdvisory regime, not gate regime.There is noAPPROVE/REJECT, nospec-approved/spec-rejectedlabel, nodeterministic verdict computation. The synthesizer returns aship_decision(fold_and_ship/needs_revision/next_brief); this is prose for the human reviewer, neverauto-applied as a label or status check.Ship-meter floor.ship_decision: fold_and_shipREQUIRESshocked_meter_avg 7.0. Below 7.0 the synthesizer MUST emitneeds_revision(single drafter pass on the existing artifact)ornext_brief(another round of panel review with a new brief).The floor is advisory wording in the comment, not a status check.Blocker veto.If ANY panelist returnsnew_blocking_findings[].length 0, the synthesizer MUST emitship_decision: next_briefregardless of the shocked_meter_avg.A blocking finding from one panel is not outweighed by threepanels rating the artifact 9/10.Single-writer interlock.Only the orchestrator writes to thePR: exactly oneadd-commentcall and oneremove-labelscall.Theremove-labelscall sweepsspec-review(triggeridempotency). NOadd-labelscall – there are no verdict labels.Panelist subagents and the synthesizer subagent return JSON onlyand MUST NOT call anyghwrite command, post comments, applylabels, or touch PR state.Single-emission discipline.Exactly one comment per panel run,rendered fromassets/comment-template.mdafter all subagentsreturn and the linter checklist runs.ASCII-only artifact.Every byte the skill writes (the comment,the synthesizer prose, any rendered fold instruction) MUST bewithin printable ASCII (U0020 - U007E). The skill inherits therepo encoding rule from.github/instructions/encoding.instructions.md(if present) and additionally enforces it on the spec artifact vialinter check 1.No-vendor-foundation language ban.The spec artifact MUST NOTcontain “CNCF”, “Linux Foundation”, “Sandbox”, “Incubation”,“W3C Process”, or “IETF RFC stream”. The persona prompts MAYreference these as pedigree (a panelist’s credibility comes fromhaving edited OpenAPI; that does not put OpenAPI’s foundationaffiliation in the spec text). Linter check 2 greps the artifactfor the forbidden token list AFTER any fold.Agent rosterAgentRoleAlways active?Swagger / OpenAPI EditorInterface-contract discipline (schemas, $ref hygiene, oneOf discriminators, conformance enumeration)YesOCI Distribution EditorRegistry-HTTP rigor (hashenvelopes, mirror tolerance, fail-closed extraction, supply-chain threat model)YesPackage-Manager Registry-Contract EditorDependency-resolution rigor (semver dialect pinning, lockfile determinism, transitive conflict policy, reserved-slot defensive MUSTs)YesW3C TAG ArchitectWeb-platform integration / architecture (extensibility, layering, fingerprinting, machine-readable contract surface)YesSpec Editor SynthesizerSame hand that drafted; aggregates panel returns, computes shocked_meter_avg, clusters convergent themes, produces fold-now / defer / reject lists and ship_decisionYesThe roster is invariant for the v0.1 lineage. Changing it requiresbumping the skill version.Topologyapm-spec-guardian SKILL (orchestrator thread) | ------ Wave 0: scope decision (orchestrator-internal) ------ | classify diff: | | - editorial-only (tiny patch, single section, no schema | | change, no fixture add) - skip Wave 3, run Wave 5 | | linter only, render lightweight comment | | - editorial-patch (default for PR-trigger) | | - skip Wave 12, start at Wave 3 | | - new-version (operator opt-in via PR body marker | | apm-spec-guardian: new-version) | | - run Wave 1 2 3 4 5 | ------------------------------------------------------------ | IF new-version mode: run Wave 1 Wave 2 first | Wave 1 (optional, new-version only): task - spec-editor-synthesizer acting as ASSESSOR -- reads issue context corpus produces SPEC_BRIEF_v0 (session-state artifact) Wave 2 (optional, new-version only): task - spec-editor-synthesizer acting as DRAFTER -- produces SPEC_DRAFT_v0 from SPEC_BRIEF_v0 | Wave 3: FAN-OUT via task tool (4 panelists in parallel) -------------------------- v v v v swagger oci pkgmgr tag (each returns JSON per assets/panelist-return-schema.json) | v -- S4 schema-validate per return v -- on malformed: re-spawn that panelist v (max 2 attempts; then placeholder) v Wave 4: task - spec-editor-synthesizer - aggregates findings across 4 panels - computes shocked_meter_avg - resolves dissent - clusters into convergent themes - emits fold_now[] defer_v0_1_1[] defer_v0_2[] reject[] - emits ship_decision honoring ship-meter floor blocker veto - returns assets/synthesizer-return-schema.json | v -- S4 schema-validate v Wave 5: LINTER (mechanical, from assets/linter-checklist.md) - 11 checks; each MUST pass - failures append to ship_prose as advisory notes - linter does NOT change ship_decision; it informs the human reviewer | Wave 6: orchestrator (sole writer) | | v v add-comment remove-labels (max:1) [spec-review] (trigger idempotency reset)Wave 0 – scope decisionThe orchestrator classifies the diff before spawning any panelist.Decision rules, in order:New-version mode.If the PR body contains the literal markerlineapm-spec-guardian: new-version, OR the diff creates a newdocs/src/content/docs/specs/openapm-*.mdfile (not an edit toan existing one), classify asnew-version. Run Waves 1 - 2 -3 - 4 - 5 - 6.Editorial-only mode.If ALL of the following hold:the diff added 50 lines AND removed 50 lines total acrossall in-scope paths,no JSON Schema file was added, removed, or had its top-levelpropertieskeys changed,no fixture file was added or removed (existing fixturecontent edits are OK),no anchor of the forma idreq-was added or removed,classify aseditorial-only. SKIP Wave 3 Wave 4. Run Wave 5linter on the modified artifact. Render the lightweighteditorial-only branch ofassets/comment-template.md(just thelinter result a one-line “no substantive spec changedetected”).Editorial-patch mode (default).Everything else. Run Wave 3- 4 - 5 - 6. Wave 1 Wave 2 are SKIPPED; the panel reviewsthe existing artifact as modified by the PR diff.Document the decision in the comment header (one line: “Scope: ;diff X/-Y lines across N files”).Wave 3 – panel fan-outSpawn the following four tasks in PARALLEL via thetasktool, onetask per persona:spec-swagger-editorspec-oci-editorspec-pkgmgr-editorspec-tag-architectEach task prompt MUST:Reference its persona file by relative path(../../agents/spec-slug.agent.md) so the subagent loads itsown scope, lens, and pedigree.Include the PR number, title, body, and full diff (passed inline),PLUS the current contents of the in-scope spec artifact ASMODIFIED by the diff (the panel reviews the post-merge state ofthe file, not just the diff).Citeassets/panelist-return-schema.jsonand require thesubagent to emit JSON matching that schema as its FINAL message.State the calibrated severity contract: “Usenew_blocking_findingsONLY for issues that would break aconformant implementation, leak a security guarantee, or invalidatea published normative claim. Usenew_recommended_findingsforsubstantive improvements. Usenew_nit_findingsfor one-lineeditorial polish. The panel is advisory; nothing you return blocksmerge; pick the severity that honestly matches your signalstrength.”State the no-vendor-foundation rule: “Your pedigree as a [persona]is part of your prompt. Do NOT propose adding the names of anystandards body, foundation, or governance program (CNCF, LinuxFoundation, Sandbox, Incubation, W3C Process, IETF RFC stream) tothe spec artifact text. Findings that recommend such additionswill be auto-rejected by the synthesizer.”State the ASCII rule: Every byte in your return JSON and everybyte of any proposed fix or replacement text MUST be within U0020U007E. No emojis, no Unicode dashes, no curly quotes.Passround(1 on first pass, 2 on subsequent rounds innew-version mode).Restate the output contract: NOghwrite commands, NO postingcomments, NO label changes, NO touching PR state. JSON return only.Wave 4 – synthesizerPass all four validated panelist JSON returns to ataskinvocationthat loads../../agents/spec-editor-synthesizer.agent.md. The promptMUST:Provide all panelist returns as structured input.Ask for:convergence_table,convergent_themes(themes flaggedby 2 panels),fold_now[](surgical single-section fixes only),defer_v0_1_1[](small patches deferrable to next patchrelease),defer_v0_2[](architectural work requiring a reservedslot in a future major),reject[](findings the synthesizerdeclines, with rationale),ship_decision,ship_prose,linter_handoff_notes.State the ship-decision rules verbatim:Ifsum(panelist.new_blocking_findings) 0 across all panels,ship_decisionMUST benext_brief.Else ifshocked_meter_avg 7.0,ship_decisionMUST beneeds_revision.Elseship_decisionMAY befold_and_ship.State the no-vendor-foundation rule: auto-reject anypanelist-proposed fix that would add a banned token to theartifact; surface inreject[]with rationale.Citeassets/synthesizer-return-schema.jsonand require JSONreturn.Restate the contract: the panel is advisory. The synthesizer doesNOT pick a verdict label. Theship_decisionis prose for thehuman reviewer, not a gate. NOghwrite commands.Validate the synthesizer return againstassets/synthesizer-return-schema.json. On failure, re-spawn oncewith the violation cited.Wave 5 – linterRunassets/linter-checklist.mdagainst the in-scope artifact set(spec markdown schemas fixtures). The checklist has 11 mechanicalchecks; each is a one-liner producing exit code 0 (or empty grepoutput where noted). Record pass / fail per check.Linter outcomes are ADVISORY: a failed check does NOT change thesynthesizer’sship_decision. It DOES surface in the comment as a“Linter notes” section so the maintainer can decide whether to foldthe fix into the same PR. Ifship_decision fold_and_shipANDany linter check failed, the comment surfaces the conflictprominently (“Synthesizer recommends ship; linter found N issuesworth folding first”).Wave 6 – render the commentLoadassets/comment-template.md, fill the placeholders from thesynthesizer panelist JSON linter results, and emit it as exactlyONE comment.Filling rules:The convergence table renders ONE row per panelist with verdict,shocked_meter, new_blockers, new_recommended, new_nits counts.The fold-now list renders the synthesizer’sfold_now[]verbatim, ordered as returned.The defer-v0.1.1 and defer-v0.2 lists render below the fold list,collapsed indetailsblocks if either has more than 3 items.The reject list renders only if non-empty.The “Linter notes” section renders only if any check failed; eachfailed check renders the check id the one-line failure summary.Full per-panel findings collapse into adetailsat the bottom.NEVER render the words “Verdict”, “APPROVE”, “REJECT”, “blocked”,“merge gate”, or any equivalent. The panel is advisory.Then sweep thespec-reviewlabel viasafe-outputs.remove-labels(idempotent on missing labels). NOadd-labelscall.Output contract (non-negotiable)Exactly ONE comment per panel run, rendered fromassets/comment-template.md.Exactly ONEremove-labelscall sweeping[spec-review].NOadd-labelscall.Subagents (panelists synthesizer) NEVER write to PR state,NEVER callgh pr comment, NEVER callgh pr edit --add-label.They return JSON. The orchestrator is the sole writer.ASCII-only across every byte the orchestrator writes.Never invent new top-level template sections or drop existingones.Loop budgetEditorial-patch mode:at most 2 panel rounds. If round 2 stillcarries new_blocking_findings, the synthesizer emitsship_decision: next_briefwith aship_prosenote that theloop budget is exhausted and the maintainer should ESCALATE(manually decide between drafting a fix or closing the PR).New-version mode:at most 3 panel rounds. Same exhaustionsemantics on round 3.Editorial-only mode:zero panel rounds (linter only).The orchestrator increments and tracks the round counter; subagentsreceive it as input but MUST NOT trust panel-side memory.GotchasRoster invariant.The frontmatter description, the activationscope list, the roster table, the topology diagram, and theschema enum MUST agree on the 4 panelists 1 synthesizer. If youchange one, change all in the same edit.Blocker veto trumps ship-meter.A panelist who returns onenew_blocking_findingand a shocked_meter of 9 means “the spec ismostly excellent but this one thing would break a conformantimplementation”. That blocker still vetoesfold_and_ship. Do notlet the synthesizer average it away.Calibrated severity discipline.The advisory regime relies onpanelists distinguishing blocking from recommended honestly. If apanelist marks every editorial nit as blocking, the synthesizer’sblocker veto becomes a denial-of-ship. The panelist prompts statethe contract explicitly; the synthesizer arbitration prose is thesafety valve.Wave 0 editorial-only is a noise filter, not a qualityshortcut.It exists so a one-line typo fix to a fixture commentdoes not summon four expert agents. It MUST NOT fire on schemachanges, anchor additions, or fixture-tree topology changes; therules above are intentionally conservative.No-vendor-foundation tokens may appear in panelist returns(apanelist can name “the W3C TAG” as their pedigree in theirsummaryfield) but MUST NOT appear in the synthesizer’sfold_now[].patch_instructionor in the rendered comment bodyoutsidedetailscollapsed sections. The synthesizer auto-rejectspanelist proposals that would add banned tokens to the artifact.ASCII enforcement is per-byte, not per-codepoint.A characterwith codepoint 0x7E is non-ASCII even if it would round-tripthrough a different encoding. The linter checks raw byte values,not the rendered visual.Subagent write enforcement is contract-based, not sandbox-based.Tool permissions are workflow-scoped, not subagent-scoped, soevery spawned task technically inherits the sameghtoolset.The “subagents must not write” rule is enforced by the promptcontract in each.agent.mdplus thesafe-outputs.add-comment.max: 1fail-soft.Spec drift across count sites.Linter check 6 catches when sec.1.3 sentence, Appendix C trailer, and Appendix D revision-historydisagree on the normative-statement total. This is the most commonfailure mode of a fold pass and is the reason the linter ismandatory before render.Relationship to apm-review-panelapm-review-panelis the general OSS multi-persona review for anynon-trivial PR in the repo.apm-spec-guardianis its narrow,spec-only sibling: a different persona roster, a different shipdecision schema (shocked_meter instead of stance enum), and amandatory linter step. The architectural shape (FAN-OUT SYNTHESIZER single-writer interlock advisory regime) isdeliberately the same so a contributor reading one can read theother. Do not merge them; the persona pedigrees and the artifacttype (spec vs code) are different enough that one-size-fits-allprompts would dilute both.