用途:为 pull request 正文提供写作方法。diff 只说明改了什么,正文负责说明为何改、影响范围、取舍决策和希望审查者关注的地方。开 PR 的机械操作由 create-pr 负责,本技能只处理正文。
主要能力:先收集事实,再起草。可从本地分支或 PR 编号获取信息,例如: git --no-pager log <base>..HEAD git --no-pager diff <base>...HEAD --stat gh pr view <n> --repo <owner/repo> --json title,commits,files,baseRefName gh pr diff <n> --repo <owner/repo> 应先读提交正文再读 diff,且须逐条核实提交信息中的说法,不转发未经验证的断言。正文需覆盖动机、关联 issue 或设计文档、有真实替代方案的决策及被否原因、影响范围、已运行的验证及结果、不确定之处。
模板:优先遵循仓库自带的 PR 模板,保留标题措辞和顺序,逐条作答但不复述模板问题文字;不适用的栏目用简短说明表示已考虑;勾选框仅在陈述为真时勾选;保留 changelog、artifact、issue 链接等机器可读标记,并确认标记位置可被解析。无模板时可使用摘要段、Review guide、What changed、Validation 的结构。
审查指引:当阅读顺序不明显、有特定关注点或影响面较大时,在摘要后加 Review guide,可含推荐阅读顺序和关注区域;小改动则并入开头,不必单设标题。
长度与删减:测试或配置类无行为变化约一段;小改动含风险面几百字;聚焦的修复或功能约四五百字;带使用方的新机制不超过一千字;大型基础改动约一千字。删减时优先去掉 diff 一眼可见的内容、测试清单、对标准工具行为的解释、重复陈述和指向描述本身的句子;保留动机、行为变化、决策与被否方案、开放问题和影响范围。
写作规范:以 ASD-STE100 为基础,主动语态、一句一主题、句子约 25 词以内,同一概念用同一术语,代码标识符和命令保持原样。
自检:首段能否让审查者判断是否与其相关;测试相关表述是否说明已运行或未运行;提交信息中的事实是否已核实;删减是否误删决策或开放问题;描述是否与当前分支状态一致;审查指引是否靠近顶部。
限制:不编造关联 ticket、不夸大测试结论、不评价自身工作、不留过期描述;重写或 force-push 后应重写正文而非追加修订日志。价格、平台支持等信息暂未提供。