infrahub-reporting-skill-gaps

Infrahub 技能差距报告器

概述

Infrahub 技能的失效悄无声息。缺少一条规则不会导致崩溃；它只会让模型多进行 11 次往返，并在自行找到正确答案前接受 4 次用户提示词。此技能会查明缺失、错误或不清晰的规则，并将改进内容起草为问题报告。它不会自行提交任何内容，也不会决定报告发往何处：它会准备一份完整且已脱敏的草稿，并交给 infrahub-reporting-issues。该技能负责管理 11 个仓库的注册表和路由、同意门槛、提交方式选择及确认。本技能的工作到移交为止。

何时使用

当用户说出以下类似的话时，触发此技能：

• “这也试得太多次了，你能报告一下这个阻碍吗？”
• “报告技能使用中的阻碍。”
• “为什么 schema 技能总是弄错？”
• “这个技能的指导是不是漏了什么？我们能修复吗？”

如果是 Infrahub、SDK 或其他 opsmill/infrahub-* 产品中的 Bug，请勿触发；这类问题应交给 infrahub-reporting-issues 处理。如果 Infrahub 日常工作顺利完成，没有遇到阻碍，也请勿触发。

工作流

按顺序执行以下步骤。在每个门槛步骤都要停下；未经明确确认，绝不要继续。

1. 检测并确认差距

从当前对话着手。只有在用户指向某个过往会话时，才查看其记录。阅读 reference.md，了解如何查找会话记录以及相关信号的位置。

然后按顺序执行以下检测阶梯，一旦阻碍描述清楚，就立即停止：

1. 验证器判定。 在同一目标上查找从失败转为通过的变化（infrahubctl schema load、object load、check run、transform run 或 pytest 运行）。这是最有力的证据，因为它不是由自我评估得出的。只有在首次尝试之前就已加载该技能时，此证据才有效。
2. 覆盖范围检查。 执行 ls skills/<skill>/rules/ 并搜索相关主题。由此确定对应文件，或确认文件缺失。
3. 修正差异。 比较首次编写的版本与最终接受的版本。该差异就是建议的规则变更，而不是对它的转述。
4. 会话形态计数。 重试、反复编辑、重复提问、转而查阅文档。这些只能开启调查，不能作为调查结论。

如果草稿只有计数数据作为依据，就还没有准备好：说明哪些探查没有结果，然后停止。参见 rules/evidence-detection-ladder.md。

2. 检查跟踪器

起草任何内容之前，先搜索 opsmill/infrahub-skills。搜索结果决定报告的形式，而不是是否需要报告：找到匹配项，就在该问题下发表评论；没有匹配项，就新建问题并明确标注置信度。参见 rules/workflow-tracker-first.md。

3. 分类：第 1 级，路由

判断阻碍属于技能缺陷、产品缺陷，还是两者都不是。只有技能缺陷才会进入第 2 级并起草报告。参见 rules/workflow-triage-classification.md。

3b. 分类：第 2 级，Bug、功能需求或文档缺口

对于技能缺陷，根据三种结果确定类型：Bug（规则或参考资料覆盖了该主题，但模型仍然出错）、功能需求（没有规则覆盖该主题，且没有转而查阅文档，或查阅后找到了答案）或文档缺口（没有规则覆盖该主题，转而查阅文档后仍未找到答案，且底层行为已经确定）。最后一个条件是门槛，而非细节：如果工作流仍在定义中，或刻意不作文档说明，那么目前就没有可记录的内容，因此不要起草报告；应向用户说明原因，然后停止。此分类决定第 6 步起草时使用的标题前缀，也是接收方进行路由的依据。参见 rules/workflow-bug-vs-feature.md。

4. 如果问题出在产品，则移交

如果分诊结果指向底层产品，而非 技能的指导内容，请在此处停止，并移交给 infrahub-reporting-issues， 而不是起草技能摩擦问题。请参阅 rules/workflow-handoff-product-bugs.md。

5. 定位产物

指出本应避免摩擦的具体规则文件，或说明缺少此类规则。 第 1 步中的探查 B 已经读取了该文件；本步骤将其结果作为 引用。无法指出相关文件或覆盖范围缺口的草稿， 尚未准备就绪。请参阅 rules/evidence-cite-the-artifact.md。

6. 起草并删去敏感信息

填写 templates/skill-friction.md， 使用第 3b 步确定的 bug:/feat:/bug(docs): 标题前缀， 以及第 2 步确定的置信度标签。根据 rules/evidence-no-customer-data.md 的要求，删去任何可识别用户基础设施或组织的信息。 这关系到安全，草稿在离开本技能之前就必须完成此操作。

标题部分包含三个版本，缺少其中任何一个，报告都 尚未准备就绪：

1. Skills，取自相关技能自身 SKILL.md frontmatter 中的 metadata.version。说明出错规则的修订版本。
2. Infrahub SDK，取自 infrahubctl info 输出中的 SDK Version 行。说明提及 CLI 标志或客户端方法的规则针对的版本。
3. Infrahub，取自同一输出中的 Infrahub Version 行。 说明涉及 schema 加载、分支行为或检查流水线的规则 针对的版本。

按照 ../infrahub-common/rules/connectivity-server-check.md 中的规定运行 infrahubctl info；运行器前缀很重要。

如果没有这些信息，维护者就无法判断指导内容是错误， 还是仅仅比实际运行的版本旧。这决定了应该重写规则， 还是为其添加版本说明。只复制版本值： infrahubctl info 也会输出服务器地址和 部署 ID，而 rules/evidence-no-customer-data.md 禁止包含这些信息。任何无法读取的版本值都写为 unknown；切勿猜测。

这会生成三个移交字段：type、title 和 body。这不会生成目标仓库： 指定目标仓库不属于本技能的职责，草稿中也不得 包含目标仓库。

如果第 2 步发现了匹配项，则改为起草评论：不写 标题，不重复问题陈述，只提供本次会话新增的 证据。

7. 移交

使用载荷 {type, title, body, searched, issue?} 调用 infrahub-reporting-issues，其中 searched 指明第 2 步搜索的仓库， 仅在找到匹配项时设置 issue。没有 repo 字段：该技能会根据 type 在自己的注册表中 确定目标，并从此负责审核关卡、 提交方式选择和确认。切勿直接提交问题或评论。请参阅 rules/workflow-handoff-to-reporting.md。

8. 转达结果

用一句话说明移交返回的结果；如果生成了问题 URL，也一并附上。接收方已经与用户确认； 这只是转达，不是再次确认。跟踪系统是持久记录； 本技能本身不保留本地状态。

规则类别

前缀	类别	说明
workflow-	工作流	顺序与关卡：跟踪系统检查、分诊和移交（移交给 infrahub-reporting-issues，处理产品缺陷或提交技能缺陷）。跳过其中任何一步，都会给维护者的跟踪系统带来噪声，或造成第二条逐渐偏离的提交流程
evidence-	证据	已提交的问题中可以和不可以包含哪些内容。关系到安全：问题正文是公开的，无法撤回

请参阅 rules/_sections.md 中的 索引。

参考资料

• reference.md：证据来源优先级、对话记录发现方式和摩擦信号。 在步骤 1 中阅读。
• rules/evidence-detection-ladder.md： 用于确认差距确实存在的四种探查方式，以及为什么仅凭计数永远无法确认。 在步骤 1 中阅读。
• templates/skill-friction.md： 在步骤 6 中填写的草稿模板。
• rules/workflow-tracker-first.md： 起草前先搜索跟踪器，并标注草稿内容的置信度。 在步骤 2 中阅读。
• rules/evidence-no-customer-data.md： 起草前需要删去哪些信息。与安全密切相关； 每次起草前都要阅读。
• rules/workflow-handoff-to-reporting.md： 将内容交给 infrahub-reporting-issues；切勿直接提交。 在步骤 7 前阅读。
• ../infrahub-common/rules/workflow-information-priority.md -- 优先查看技能内容；遇到确实存在的信息缺口时，如何查阅 docs.infrahub.app

反模式

• 未提出规则变更就提交。 如果摩擦报告没有指出要创建或编辑哪个文件， 以及文件中应该写什么，就无法采取行动。维护者不应当需要根据症状描述反向推导修复方案。
• 不知道涉及哪个技能就提交。 如果步骤 5 无法指出具体技能和规则文件（或确认不存在规则文件）， 报告就还没准备好起草。
• 提交重试次数。 往返轮次、提醒次数和编辑变更量衡量的是一次会话，而不是规则集。 这些数值会因与技能无关的原因而增加，例如请求不明确、实例响应慢或用户改变主意。 它们只能开启调查；要结束调查，还需要验证器的判定或覆盖情况检查。
• 未检查跟踪器就起草。 步骤 2 并非可选。未做检查就起草报告，不是重复已有的待处理问题， 就是丢弃第二位观察者本可找到的唯一线索。
• 重复提交，而不发表评论。 如果已有问题涵盖了该摩擦，再开一个问题会把证据拆散到两个讨论串中。 评论才是更有价值的内容：它能提供维护者需要的佐证。
• 隐瞒首次发现。 单次观察只是薄弱证据，并非零证据。将其标记为 unconfirmed，由维护者判断； 保持沉默只会确保第二位观察者永远发现不了它。
• 未删减就粘贴原始错误文本。 错误消息可能包含文件路径、主机名和节点类型，从而识别出客户的基础设施。 请改述，不要直接粘贴。
• 未交接就直接提交。 此技能没有征求同意的环节、没有重复项搜索，也没有自己的提交方式。 在此处运行 gh issue create，或声称问题已提交，都会绕过 infrahub-reporting-issues 提供的唯一审核环节， 并有导致再次未经审核提交的风险。