将 GitHub Issue 转换为经过测试的 PR

将 GitHub issue 转化为经过测试且验证过的 Pull Request。该技能负责整个流程的管控——包括前提条件验证、重复任务排查、代码级修复以及准确的 CI 报告；而相关的 GitHub 及开发技能则分别处理各自的特定环节。

适用场景

“修复 issue #123 并创建一个 PR。”
“实现这个 GitHub 功能需求。”
“将此错误从 issue 状态推进到 CI 测试通过的状态。”

不适用于：审查现有的 PR，或回答那些并未要求进行代码修改的问题。

使用 terminal 运行命令 gh issue view <N> --comments。问题正文是提交时的快照；而最新的评论则反映了当前的实际状态：已合并的部分修复、新的根本原因分析、维护者的决策，或是针对你的疑问，这些都会改变任务内容。同时，还需通过 read_file 功能查阅仓库中的相关说明（如 AGENTS.md 和贡献指南）。当明确了当前要求实现的功能、未完成的目标以及所有尚未解答的讨论问题后，即可完成此步骤。

2. 排查是否存在重复工作

在开始编写任何代码之前，先运行 gh pr list --search "#<N>" --state all，并结合该问题的至少两个关键词或同义词组合进行查询（如 gh pr list --search "<subsystem> <symptom>" --state open"）。热门问题往往会有多个独立的修复方案，重复开发只会浪费时间和精力，也无法获得应有的认可。同时，还需检查是否有最近的提交已经解决了该问题：git log --oneline -20 -- <relevant files>。当您已了解所有与之相关的待处理PR以及最近的提交记录，或者确认不存在此类内容时，即可进入下一步。

3. 根据当前代码及设计初衷验证问题前提

在当前的默认分支上，利用失败的测试用例或测试 fixture 复现缺陷或展示缺失的功能，通过 search_files 和 read_file 功能定位问题出现的路径。随后需要回答第二个问题：这个“缺陷”实际上是否是刻意的设计？针对需要修改的代码，运行 git log -p -S "<symbol>"，仔细阅读原始提交的意图——很多时候，那些被视作缺失环节或限制的内容其实正是预期的功能。此时不应盲目实现功能，而应先质疑那些过时或有误的问题描述。只有当当前代码中能够明确显示出问题的根本原因或功能缺口，并且该修改并不违背既定的设计意图时，才能继续下一步。

4. 明确验收标准与风险点

列出验收标准、接口要求、数据迁移/状态变更方案、兼容性要求、安全与隐私考量、发布计划以及回滚策略。并将每一项标准对应到具体的测试用例或明确的验证方法上。只有当评审过程有了清晰的规范框架时，才能进入下一步。

5. 实现最小化的完整修改——并修复相关类结构

请在独立的分支或工作树中进行开发。当错误类型需要时，可启用 systematic-debugging 或 test-driven-development 功能。首先编写回归测试，再实现修复代码。确定修复方案后，使用 search_files 查找同一类错误在其他相关位置的出现，并在该 PR 中一次性修复整个问题——留下未修复的同类问题比完全不修复还要糟糕。每修改的一行都必须与原始问题相关联，严禁随意清理代码。只有当目标测试通过、原有错误不再出现，且所有相关位置都得到修复或被明确排除后，才算工作完成。

6. 验证回归测试的有效性（破坏性测试）

暂时恢复正在测试的函数原有的行为，运行新的测试并确认其失败；之后再恢复修复后的版本，确认测试通过。无论是否应用修复，都能通过的回归测试其实毫无意义。只有当测试在应用修复前的代码上明确失败时，才算验证完成。

7. 运行仓库质量检查后立即提交 PR

对相关代码片段运行格式化、代码检查、类型检查以及仓库规定的标准测试入口；同时在对比代码差异上使用 requesting-code-review 功能。之后立即推送代码并提交 PR——PR 才是触发 CI 测试的起点，而 CI 测试的延迟往往是最大的瓶颈，切勿拖延已完成的代码。关于 PR 的编写规范，可参考 github-pr-workflow：采用常规的分支/提交机制，正文部分需说明问题、解决方案、测试用例、潜在风险以及排除项。最后再次检查 PR，确认 HEAD SHA 值、基准分支、标题及包含的文件无误。只有当 PR 包含预期的代码差异且 CI 测试正在运行时，才算任务完成。

8. 如实反馈 Shepherd CI 结果并形成闭环

可通过 gh pr checks / gh run view --log-failed 查看实时检测结果及失败日志。需区分是由代码差异导致的故障，还是原有基准或基础设施问题——若不确定，可在默认分支上复现问题；仅针对真正的基础设施偶发故障重新运行测试一次。在没有实时的确切状态证明之前，绝不能声称“通过”、“已合并”或“已发布”。当 PR 被合并后，应在相关问题下留言，附上 PR 链接及简短说明，以便问题报告者能够追踪到问题的解决过程。只有当 CI 状态、剩余阻碍以及问题讨论帖均反映真实情况时，才算完成。

常见误区

未阅读问题评论便开始编码，或草率检查是否存在重复 PR，又或直接查看当前代码。
将原始提交中明确为有意设计的功能“修复”掉。
仅修复了某个调用点的问题，而其他类似位置仍存在相同缺陷。
发布了在未应用修复的情况下也能通过的回归测试。
提交的 PR 中包含未运行的测试或无关的格式改动。
仅因存在 PR 就声称问题已解决。

验证方式

已完整阅读问题讨论帖，计划中已体现最新评论状态。
使用问题编号及2种关键词变体执行了重复PR扫描。
在当前代码环境中复现了问题现象，并通过Git历史记录验证了设计初衷。
经验证，若不进行修复，回归测试将会失败。
已修复相关调用点，或明确排除了其影响。
所有被修改的代码行均与该问题相关联。
CI运行状态仅基于实时检测结果汇报；问题描述中已附上PR链接。

Hermes Agent Docs i18n