develop-issue

开发 Issue

快速开始

调用时必须且只能提供一个同仓库 GitHub issue 引用：

/develop-issue #123
/develop-issue https://github.com/<owner>/<repo>/issues/123

此技能是一个目标导向的控制器。它负责协调现有工作流技能，遵守它们的约定和仓库防护措施，并且绝不会合并拉取请求。

最终目标

实现可用于生产的代码，所有可见的 PR 检查均通过，并解决所有本地审查发现的问题和 PR 审查评论。

将“可用于生产”视为有证据支撑的就绪评估，而非零风险保证。不要声称绝对确定或使用类似措辞，除非有充分依据。

最终状态

• goal-met：可用于生产的证据支持 goal-met；所有必需的退出门槛均已满足，所有可见的必需和可选 PR 检查均已通过。
• human-blocked：推进工作需要人工判断、外部访问、产品或设计决策、权限、机密信息、方向冲突，或有效但超出 issue 范围的工作。

尚有由人工负责解决的阻塞项时，不得报告 goal-met。

必需的子技能

在设置分支或开始实现之前，确认 Agent 环境中已安装以下技能：

• new-branch
• implement
• diagnosing-bugs
• review-code
• finish-pr

implement 会在约定的节点调用 tdd 和 review，因此也必须安装这两项技能。

如果缺少任何技能，请在开始实现前停止。报告缺少的技能名称和安装指引：

npm_config_ignore_scripts=true npx skills@latest add patinaproject/skills --skill new-branch --skill review-code --skill finish-pr -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@implement -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@tdd -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@review -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@diagnosing-bugs -y

implement、tdd、review、diagnosing-bugs、writing-great-skills 和 prototype 的安装提示有意跟随其源目录的默认分支。需要固定安装版本的使用者可以在这些源地址后添加 #<git-ref>。

条件路由

条件路由并非一概适用的前置条件。只有当 issue 触发相应路由时，才检查指定技能是否可用；只有在已触发的路由缺少技能时，才停止并报告缺少的技能名称和安装指引。

已触发条件路由的安装指引：

npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@writing-great-skills -y
npm_config_ignore_scripts=true npx skills@latest add mattpocock/skills@prototype -y

• 如果 issue 会更改可安装技能包的内容范围，请查阅 writing-great-skills：技能入口说明、frontmatter 或描述、工作流约定文本、示例、参考资料或随附的辅助脚本。在 implement 开始构建更改前，先应用其审查结果。
• 仅当 issue 明确要求进行一次性探索、状态模型合理性检查、UI 方向探索或类似原型工作时，才使用 prototype。除非 issue 明确要求提交原型产物，否则在本地审查前删除或吸收原型产物。

除非 issue 明确要求，否则不要为上游规划、分流、架构审查、交接或对话模式技能添加常规的 /develop-issue 路由。

输入约定

1. 接受一个不带前缀的 issue 编号、#<number> 或同仓库 GitHub issue URL。
2. 缺少 issue 引用时予以拒绝。
3. 多个 issue 引用时予以拒绝。
4. 跨仓库 issue URL 时予以拒绝。
5. 通过当前工作目录默认的 gh 仓库解析 issue。
6. 只有当验收标准、范围、仓库规则和设计决策均可执行时，才将该 issue 视为已获准实现。

如果 issue 缺少可执行的验收标准、与仓库规则冲突、需要设计决策、依赖外部访问，或存在其他需要 issue 中未记录的判断的情况，请暂停并交由人工处理。

必须满足的退出门槛

• 已涵盖问题范围和验收标准。
• 已运行仓库文档中规定的验证，并记录结果。
• 如果更改包含可执行行为，已添加或更新相关测试。
• 已修复或处理本地 review-code 发现的问题。
• 已修复或处理 GitHub PR 审查评论以及 finish-pr 显示的托管审查评论。
• 执行 finish-pr 后，所有当前可见的必需和可选 PR 检查均通过，才能报告 goal-met。
• 如果 PR 检查失败与分支范围无关，最终报告中必须在 human-blocked 下给出具体处理方式；只要仍有任何可见 PR 检查失败，就不得报告 goal-met。
• 仅当剩余风险和测试缺口具体、与问题相关且有助于人工决策时，才报告这些内容。

对于此技能，所有可见 PR 检查均包括必需和可选检查。

能力映射

• new-branch：设置与问题关联的分支（前置条件见工作流步骤 4）。
• implement：根据验收标准实现问题所需的更改——在约定的切入点使用 tdd，运行文档规定的验证，并提交到分支。
• diagnosing-bugs：根本原因不明确、缺少复现步骤、行为不稳定或出现性能回归时使用。
• review-code：在全新上下文中审查本地分支差异，检查正确性和与合并相关的风险，与构建者的上下文相互独立。
• finish-pr：提交、推送、创建或更新 PR、运行 PR 检查、处理 PR 反馈循环，并报告是否已准备好合并。
• writing-great-skills：更改可安装技能包的外部接口时使用。
• prototype：仅用于明确要求的一次性探索。

工作流

1. 阅读 AGENTS.md 和 CLAUDE.md（如果存在），以及它们引用的任何文档。

2. 验证唯一且属于同一仓库的问题引用，以及所需的子技能。

3. 在设置分支之前，将问题标记为已开始。此“我开始工作了”步骤包含两个独立操作：自行指派和更新 GitHub Project 状态。尽最大努力分别执行两项操作；两者都不会阻碍实际工作，也都不会导致 human-blocked 中止。

   自行指派：

   • 从问题的 assignees 字段读取当前受指派人（例如 gh issue view <number> --json assignees）。仅当列表为空时才指派。
   • 如果问题没有受指派人，则通过一次问题级调用将问题指派给当前通过 gh 认证的用户：运行一次 gh issue edit <number> --add-assignee @me。
   • 将“我自己”解析为 @me；绝不要硬编码用户名，以便此技能可在所有使用者间复用。
   • 如果问题已有一名或多名受指派人——无论是 @me 还是其他人——都不执行任何操作。不要额外添加 @me。
   • 这是一次问题级调用，而不是针对每个项目条目的操作。不要将指派操作添加到 new-branch，它仍然是纯本地分支工具。
   • 如果指派调用失败（权限不足、缺少写入权限、API 错误），则跳过并记录原因，然后继续设置分支和实现。 GitHub 项目状态：
   • 通过问题的 GitHub Project 项（即该问题的 projectItems 数据），检查其现有的 GitHub Projects。对于每个现有的 GitHub Project 项：
     • 检查项目项，找到一个兼容字段，其中 In progress 是一个完全匹配的可选项，并将该项目项更新为 In progress。
     • 不要将问题添加到项目中。不要创建项目字段或状态选项。
     • 如果项目缺少兼容的状态字段、缺少 In progress 选项，或因权限问题导致项目项检查或更新失败，则跳过不兼容的项目项并继续。
   • 记录项目状态更新结果和自行分配结果，包括每个已更新项目项以及跳过项目项的原因，以便在最终报告中说明。

4. 满足分支设置前提：确认当前分支是目标问题关联的分支（其名称按照 new-branch 采用的 <issue>-<slug> 约定编码了问题编号）。仅当检查通过时才跳过 new-branch；否则——包括工作树从一个非默认但未关联问题的分支开始时——运行 new-branch 建立问题关联分支，或者在托管环境提供的分支无法或不应重命名时说明这一偏差。

5. 应用 Conditional Routes 部分中触发的条件路由。

6. 通过指出实际状态与最终目标之间当前的差距，选择下一项能力。

7. 不要将实现、诊断、本地审查或发布视为固定的强制顺序。调用能够消除当前阻塞或准备度差距的能力。

8. 在本地审查之前，以及在判断是否已准备好最终发布之前，运行仓库文档中规定的验证。

9. 检查是否存在可审查的本地更改：相对于默认分支合并基点的已提交分支差异、已暂存更改、未暂存更改或未跟踪文件。

10. 存在可审查的本地更改时，调用 review-code 并遵守其完整约定。明确使用 develop-issue 即表示已批准此项必需的本地审查门禁：无需再次征求用户确认，直接调度新的只读审查者。严格遵守 review-code 的边界：不得在同一线程中改用其他方式，不得编辑文件、暂存、提交、推送、发表评论、修改审查线程或以其他方式更改工作树。若无法调度新的审查者，或 review-code 报告了停止条件，则停止。

11. 通过 Review Finding Router 处理本地审查发现。

12. 使用 finish-pr 处理提交、推送、创建或更新 PR、观察可见检查、PR 反馈循环以及报告是否已准备好合并。只有在本地验证和 review-code 均无问题、因不存在可审查的本地更改而跳过，或每项本地发现都已有记录在案的 ready-for-agent、ready-for-human 或 wontfix 处置结果后，才调用 finish-pr。

13. 持续循环，直到达成最终目标，或遇到阻止进一步推进且由人工负责处理的阻塞问题。

在长时间运行或可恢复的执行过程中，使用最终报告中的词汇维护简洁的检查点状态：问题引用和 URL、分支名称、最终状态、有意义的更改、准备度、阻塞问题以及下一步操作。从该状态恢复执行并继续，直到到达终止工作流状态：生产就绪证据支持 goal-met，或存在有记录的 human-blocked 停止状态。

审查发现路由器

将发现归类为以下结果之一，且只能归为一种：

结果	适用情况	后续操作
ready-for-agent	预期行为明确，或可以在本地收集证据	将明确的行为变更路由到 implement；将根本原因不明确、缺少复现步骤、行为不稳定或性能回退路由到 diagnosing-bugs
ready-for-human	发现需要判断、外部访问、手动测试、设计意见、缺失信息、范围变更、产品决策、权限、相互冲突的指示，或属于问题范围之外但合理的工作	停止循环，并报告阻碍因素及已核查的证据
wontfix	发现已过时、不正确、与仓库规则冲突，或被有意拒绝	在报告中礼貌地说明；仅当未来的审查者否则会再次提出同一问题时，才添加简洁的代码注释

v1 中没有 needs-info 状态。信息不足时应归为 ready-for-human。

最终报告

报告指南

进度更新、可恢复检查点和最终交接应说明发生了哪些变化、工作是否已就绪或受阻，以及人类接下来应采取什么行动。为决策在内部保留验证证据。只有在验证失败、跳过、中断、改变就绪状态、解释阻碍、指出剩余风险或产生人类后续行动时，才报告验证详情。

将子技能的输出转化为结果、就绪状态、阻碍和后续行动方面的表述。进度更新应指出当前检查点和下一步行动，不要重复检查清单。

工作流停止时，应优先面向人类撰写，而不是记录流程。先说明结果，只呈现会影响读者理解或行动的详情。

包括：

• 用 1-3 条有意义的要点说明发生了哪些变化。
• 说明工作最终进展：包括 issue、PR 和分支链接。有 URL 时添加链接；没有时直接写出名称。
• 仅当项目状态更新改变了就绪状态、失败、跳过、解释阻碍或产生人类后续行动时，才报告更新结果。
• 仅当 issue 自我指派失败、改变了就绪状态或产生人类后续行动时，才报告结果。指派成功时不提。
• 终止状态：goal-met 或 human-blocked。
• 生产就绪依据。
• 验证命令和结果，以最高实用层级进行概述。如果所有检查均通过，将常规验证合并为一行简洁说明。
• 新增或更新的相关测试。
• 仅当子技能的停止原因会改变人类接下来的行动时，才说明这些原因。
• 本地审查结果和发现的处理情况。
• PR 审查和检查反馈状态。
• 仅当最新的 review-code 结果会影响审查者的信心或后续行动时才报告；如果没有可审查的本地更改而跳过，也仅在会影响审查者信心或后续行动时说明。
• 如有由人类负责处理的阻碍，予以说明。
• 如有 wontfix 解释，予以说明。
• 仅说明具体且相关的剩余风险或测试缺口。
• 如果运行了 finish-pr，说明 PR URL 和就绪状态。

清晰具体地说明：

• 失败或跳过的检查、尚未解决的风险，或仍需人类采取的行动。
• 对于未运行或未通过的验证，写明确切命令和阻碍。
• 如果运行时需要报告令牌或预算，应将其放在结果之后，避免喧宾夺主。

删除或尽量精简以下内容：

• 所有检查均通过时，逐条列出运行过的所有命令。
• 反复声称 lint、类型检查、测试、钩子和 PR 检查均已验证。
• “我检查了状态、审阅了差异、运行了检查”等泛泛的流程叙述。
• 所有检查均通过时，完整列出 PR 检查项目。
• 除非会改变人类接下来的行动，否则不提可合并状态、审查情况或无关的脏文件状态。
• finish-pr 的就绪门槛，例如工作树干净、head SHA 一致、合并状态、检查清单或审查线程数量；如果均已通过，将其合并到验证说明中，除非某项门槛失败会改变人类接下来的行动。

良好的最终输出

issue 190 的示例：

Done: [#190](https://github.com/patinaproject/skills/issues/190) is implemented
on [PR #197](https://github.com/patinaproject/skills/pull/197)
([branch `190-human-focused-final-output`](https://github.com/patinaproject/skills/tree/190-human-focused-final-output)).

Changed:
- `develop-issue` final reports now lead with outcome and meaningful changes.
- Routine verification is collapsed unless something failed, skipped, or needs
  human attention.

Verified: routine checks passed.

Needs human attention: none before review.

不良的最终输出

避免将最终输出写成流程记录：

Implemented issue #190.

Verification:
- develop-issue workflow test passed.
- markdownlint passed.
- type-check passed.
- commit hook passed.
- PR check Test Gate passed.
- PR check code-review passed.
- PR is MERGEABLE and CLEAN.

Child skills invoked: new-branch, implement, review-code, finish-pr.
No unrelated dirty files except local config. Goal marked complete.

仅将不良格式作为反面示例；不要照搬其结构。