fix-pr

/fix-pr 会恢复拉取请求预期的工作流结果。它会找出最早的因果故障，对其原因进行分类，实施最小且持久的修复，并根据所有必需检查验证修复后的提交。

本地工作和持久记录

使用文件系统协议和 python3 <skill-dir>/scripts/p2p_filesystem.py --repo <root> resolve .p2p/work/<slug>/contract.md 解析路径。使用 save .p2p/work/<slug>/contract.md <report-name> --from <file> 保存报告，以便在替换前保留历史记录。

当适用规范的 .p2p/work/<slug>/contract.md 时，请在 .p2p/work/<slug>/ 中查找已保存的候选版本和报告。将诊断、修复结果、保留的安全证据以及新旧候选版本的准确标识保存到 .p2p/work/<slug>/ci-repair.md，并遵守协议的保留规则，保留先前记录。将临时日志放入 .p2p/tmp/；在声称已移交之前，先保留所需证据。对机密信息进行脱敏；对于不适合提交到 Git 的证据，请使用协议规定的持久引用和校验和记录。仅保存本地报告并不会授予 Git 操作权限；下方明确规定的 /fix-pr 调用授权仍是独立的。候选版本发生更改时，必须重新审查并验证；绝不改写旧的判定结果。

调用方式

接受一个仓库目标：

• /fix-pr #123
• /fix-pr https://github.com/acme/project/pull/123
• /fix-pr <workflow-run-url>

只要目标信息足以判断，就从拉取请求或工作流运行推断相关工作流。

安全防护

编辑前，检查分支和工作区。只有当前分支和提交能确定目标 PR 的头部提交或工作流提交，且工作区没有无关更改时，才继续。如果无法确定目标、凭据或权限不可用，或者分支状态导致修复存在歧义，则停止并返回 NOT FIXED。

只提交范围明确的修复，只推送到目标 PR 的头部分支，绝不强制推送。

将诊断和验证绑定到准确的目标提交 SHA。如果 PR 在修复期间发生更改，应停止操作并重新确定目标，而不是悄悄跟进新的提交。

对于来自分支仓库或其他不可信的 PR，不得暴露机密信息、批准执行特权工作流、扩大权限或削弱隔离。如果所需验证依赖不可用的安全执行路径，则停止并返回 NOT FIXED。

保留暴露故障的验证边界：

• 保留所有必需的作业、测试、断言、lint/类型检查、覆盖率阈值、CI 矩阵项和失败条件。只有符合 Forbidden repairs 中的证据规则，才能替换错误或过时的检查。
• 对于仅涉及工作流的修复，必须以相同的失败语义运行相同的质量检查。
• 如果仓库存在合适的切入点，针对产品缺陷或测试缺陷添加或强化聚焦的回归测试。使用独立的行为断言，而不是照搬实现中的计算。
• 修复范围仅限于故障。重新运行只能作为证据，不能算作修复。

工作流

1. 确定预期操作

确定失败的工作流原本要保证什么，例如在合并前验证 PR 分支，或对特定提交运行必需的检查。根据该保证定义成功标准。

当相关行为由验收契约协议 以及其中关联的工单和验收契约定义时，请阅读它们，并保留修复所依据的修订版本、需求 ID、承诺结果、边界、约定的切入点以及独立判定依据。如果无法获取契约或其含义有歧义，只能继续实施正确性不依赖猜测缺失需求的修复。 报告这一缺口；CI 故障并不授权更改工单中的承诺。

2. 编辑前先诊断

检查工作流运行、失败的作业和步骤、日志、工作流 YAML、相关更改，以及目标 PR 的分支保护或规则集要求的检查。 从最早的因果性故障入手，然后查找并行作业中的独立故障。记录工作流、作业、步骤、命令和观察到的错误。

根据单位时间的预期证据量、上下文成本和计算成本，选择本地复现、推送 GitHub Actions 运行，或两者兼用。当本地检查能快速隔离原因时，使用本地检查；当权威远程工作流依赖特定环境或本地复现成本较高时，优先采用远程工作流。 如果现有产物和有针对性的静态检查能回答问题，就使用它们；避免重复运行等效检查。

更改任何内容之前，先对主要原因分类：

• PRODUCT：分支代码、测试目标或生成的输出有误。
• WORKFLOW：GitHub Actions 配置、权限或作业连线有误。
• EXTERNAL：依赖项、运行器、凭据或服务不可用。

对于 EXTERNAL，不要为了弥补不可用的能力而更改产品或工作流代码。只有在获得授权且可独立验证时，才解决外部条件；否则返回 NOT FIXED。

将不稳定性视为置信度修正因素。如果没有相关更改却重新运行，且成功通过，则在理解不确定性之前，结果应为 NOT FIXED — WORKFLOW GREEN — FLAKE NOT RESOLVED。

3. 修复并验证

在负责该故障的层面实施最小且完整的修复。保留必需检查及其失败语义，但须遵守 Forbidden repairs 中的证据规则。对于产品和测试缺陷，在宣布成功前，添加或加强针对性的回归证据。

将产品或测试修复对应到受影响的要求及其可观察结果。记录替代证据，以及它为何仍能验证同一承诺。将无关的验收缺口清晰列出，不要把此 CI 修复扩展成完整实现或证明流程。

先运行成本最低、信号最强的验证，无论是本地还是远程。如果权威 GitHub 工作流是更高效的证据来源，就将其作为主要验证；只有在更广泛的本地检查能提供值得其成本的额外证据时，才运行这些检查。 验证目标 PR 的分支保护或规则集报告的每项必需检查，而不仅是最初失败的作业。对于工作流运行目标，如果有相关 PR，就使用该 PR；否则验证该运行所包含的每项检查，并说明无法确定分支保护要求。只有当必需检查在完全相同的已修复 SHA 上成功时，才计为通过验证。 待处理、排队、已取消、超时、已跳过、缺失或过期的结果都不能算作成功验证。如果环境提供等待机制，就使用该机制；不要自行设定轮询间隔、等待时限或修复尝试次数上限。 如果没有等待机制，则返回 NOT FIXED — VERIFICATION PENDING 并附上运行链接。如果原因不确定、必需能力不可用、修复会削弱质量，或修复导致无法解释的质量回退，就停止。确认已推送修复后的提交，且所有必需信号仍可衡量。

禁止的修复

确保必需的质量信号仍可衡量。不要删除或跳过测试、禁用 lint 规则、降低覆盖率、将检查设为可选、吞掉失败、无条件添加 continue-on-error、添加任意重试，或注释掉工作流步骤。只有当源契约和证据证明检查有误或已过时时，才能更改检查。替代方案必须为相同的承诺提供更强且有效的证据。记录原因和受影响的需求 ID；更改检查并不授权更改承诺。

不要重新设计工作流、清理无关代码，或用一次成功的重新运行掩盖尚未解决的故障。

完成

返回以下结果之一：

• FIXED：已了解原因，完成持久修复并通过针对性验证，所需质量信号得到保留或增强，修复后的提交已推送，且目标的所有必需检查均已通过。
• NOT FIXED：故障仍未解决、所需能力不可用、工作区不安全、修复会削弱质量，或仅有一次原因不明的重跑通过。

FIXED 表示工作流已修复，不代表每项工单要求都已证明。

无论哪种结果，都要报告预期操作、故障分类、最早的因果错误、变更文件、执行的验证、必需检查状态，以及 NOT FIXED 时剩余问题的原因。 同时提供修复后的 SHA、受影响的要求 ID、替换的证据，以及任何验收缺口。若存在已保留的契约修订版本，也要记录。 任何候选版本变更都会使先前的证明仍绑定到旧候选版本。产品行为、验收证据或相关测试发生变更时，必须针对每项要求重新执行 /prove，方可验收。CI 通过不能刷新证明。 指出过期的证明和评审结果；如果相关步骤已被要求或属于必需步骤，则移交给 /prove 和代码库的评审流程。

调用 /fix-pr 即表示授权对目标 PR 或工作流运行执行限定范围的检查、编辑、提交、推送和工作流重跑。但这并不授权强制推送、变更目标分支之外的内容，或采用削弱验证的变通方法。

以 Next steps: 结尾，并提供按顺序编号（1.、2.……）的适用操作，以便逐项引用。对于 FIXED，使用下方适用的调用刷新过期报告；若两者均适用，则提供 /merge-readiness <PR URL> 以及已保存的报告引用。

/prove <saved contract>; candidate <repaired SHA>
/review-implementation <repaired candidate> against <comparison base>

对于 NOT FIXED，提供工作流中的确切失败检查命令及其观察到的失败，或指出具体缺失的输入或需要人工作出的决定。不得声称已获验收或拥有合并权限。