pr-prep

PR 准备技能

通过遵循目标仓库的实际惯例、证明分支内容，并起草便于审查的 PR 正文，准备外部贡献。执行整个工作流；在用户明确批准准确的标题、正文、基准分支和远程仓库之前，不要提交任何内容。

关键约束

• 原因：防止重复工作。 在打包贡献之前，检查未关闭和已合并的议题/PR，以及当前默认分支。
• 原因：尊重目标仓库。 阅读目标仓库的 AGENTS.md、CONTRIBUTING.md、PR 模板、发行说明和近期已接受的 PR；本地 AgentOps 惯例不得凌驾于上游贡献规则之上。
• 原因：保持范围单一。 如果分支混有无关主题、已合并的更改、生成的杂项或机密信息，请停止。
• 原因：确保证据真实。 运行仓库规定的构建、代码检查和测试命令；检查未通过时，绝不能标记为已完成。
• 原因：避免破坏性历史编辑。 只有用户另行授权改写时，才可拆分提交；否则仅提供建议。
• 原因：外部发布会改变状态。 先起草并展示准确的产物，在执行 gh pr create 或推送之前，必须获得明确批准。

范围与模式

用于外部仓库和开源贡献准备。不要用于常规内部提交或 AgentOps 直接发布到 main 的流程。

触发词 pr-research 会进入上游研究模式：在准备工作之前，先调查已有工作、分析贡献指南、追溯已合并的 PR，并研究维护者的惯例。将研究记录保存到 .agents/research/YYYY-MM-DD-upstream-<slug>.md。

输入包括目标仓库、当前贡献分支、可选议题，以及可选的目标基准分支/远程仓库。准备工作可以写入本地文件；但这不代表获得了发布、改写历史或联系维护者的授权。

工作流

1. 检查已有工作。 确认上游默认分支和远程仓库。根据行为、符号和议题 ID 搜索未关闭/已关闭的议题及 PR。若发现竞争中的贡献，在用户决定如何处理之前停止。
2. 了解惯例。 阅读仓库说明、贡献文档、PR 模板、CI 配置、变更日志政策、近期已合并的 PR 和提交主题。记录维护者使用的准确标题、正文和测试惯例。
3. 证明范围独立。 比较合并基点范围，列出更改的文件和提交，并按行为分组。移除或报告无关文件、机密信息、生成产物、调试输出，以及基准分支上已有的更改。
4. 验证分支。 运行目标仓库文档中规定的格式化工具、代码检查、构建、测试和任何贡献专用检查。记录命令、退出状态和相关结果。失败的检查在草稿中仍应标为失败。
5. 分析提交。 对少于 50 行且涉及四个文件的差异，建议合并为单个提交；其他情况请参阅 commit-split-advisor.md。建议中应列出有顺序的文件组，并确保每个提交都能成功构建。不要改写提交历史。
6. 起草 PR。 将 .agents/pr-prep/YYYY-MM-DD-<slug>.md 写入以下内容：拟定标题、上游仓库/基准分支、关联议题、简洁的原因/内容概述、更改列表、仅包含已执行证据的测试计划、兼容性/回滚说明，以及与审查者相关的风险。严格遵循上游模板。
7. 检查点——必须由用户审查。 展示标题、正文、基准分支、远程仓库、分支、验证结果，以及所有失败或尚未测试的检查。征求批准或修改意见，并等待回复。保持沉默、要求“准备”，或此前授予的推送权限，都不代表批准创建此 PR。
8. 获批后才提交。 如果 HEAD 已移动，重新检查差异和验证结果，然后运行 gh pr create --title <approved-title> --body-file <approved-file> --base <approved-base>。报告生成的 URL；除非用户要求，否则不要进一步修改 PR。

PR 正文结构

## Summary
<what changed and why; 1-3 sentences>

## Changes
- <reviewable behavior or implementation point>

## Test plan
- [x] `<command>` — <result>
- [ ] <not run> — <reason>

Fixes #<issue>

仅将已执行的 PASS 证据标记为已勾选。保留失败或跳过的检查，不要隐藏。如果上游政策允许，将关闭关键词放在末尾。

输出规范

• 制品目录： 本地评审草稿存放在 .agents/pr-prep/，可选的上游调研存放在 .agents/research/；当前 Git 分支即为代码制品。
• 文件名约定： YYYY-MM-DD-<contribution-slug>.md；不要覆盖无关草稿。
• 序列化／架构格式： 遵循上游 PR 模板的 Markdown，包含标题、远程仓库／基准分支、摘要、变更、测试计划、风险和议题关联。
• 验证命令： 在请求批准前，运行 bash skills/pr-prep/scripts/validate.sh、目标仓库中有文档说明的检查、git diff --check，以及适用于该仓库的密钥扫描。
• 后续交接： 首先由用户评审；只有在获得明确批准后，才通过 gh pr create --body-file 提交给上游维护者。

质量标准

• 符合约定： 标题、模板、提交结构和检查均遵循上游规范。
• 范围独立： 每个变更文件都服务于同一项贡献。
• 证据充分： 测试计划区分通过、失败和未运行的检查。
• 便于评审： 简洁清晰地说明理由、行为、风险和兼容性。
• 安全： 不包含密钥、无关变更、破坏性重写，也不隐式提交。
• 可复现： 明确指出分支范围、命令、基准分支、远程仓库和草稿路径。

示例

用户说：“为向上游提交 PR 准备此分支。”

检查上游规则和以往工作，验证分支，编写本地 PR 草稿，并在评审检查点处停止。

用户说：“使用我刚批准的草稿提交 PR。”

确认草稿和 HEAD 仍与获批状态一致，然后只创建该 PR，并报告其 URL。

故障排除

问题	响应
存在重叠的 PR	展示重叠部分并等待用户指示
分支混杂多个主题	建议拆分为不同组；未经授权不要重写
必需检查失败	在草稿中保留失败状态，不要暗示已准备就绪
缺少上游模板	根据最近合并的 PR 推断，并标明该假设
批准后 HEAD 发生变化	重新生成证据并再次请求批准

参考资料

• pr-prep.feature — 可执行的行为约定
• commit-split-advisor.md — 可构建的提交分组
• case-study-historical-context.md — 历史贡献背景
• lessons-learned.md — 可复用的准备经验
• package-extraction.md — 软件包提取指南