pr-writer

PR 撰写器

将 PR 正文写成供审阅者阅读的说明，而不是变更日志、模板、验证日志或逐文件摘要。

检查变更

需要已通过身份验证的 gh。检查当前分支、工作树、PR、基分支、提交和完整差异：

git branch --show-current
git status --porcelain
gh pr view --json number,title,body,url,baseRefName,headRefName
gh repo view --json defaultBranchRef

如果 gh pr view 报告不存在 PR，请继续创建首个 PR。对于现有 PR，使用其 baseRefName；否则使用仓库默认分支。设置 BASE，然后检查：

git log "$BASE"..HEAD --oneline
git diff "$BASE"...HEAD

如果当前位于 main 或 master，请先创建功能分支。确保预期变更已提交，并审阅整个分支的差异，而不只是最新提交或现有 PR 文本。

核心规则

• 先说明具体变更的行为、受影响的部分以及对审阅者的影响，再介绍实现细节。
• 仅在有帮助时说明动机、风险、权衡、迁移或审阅重点。
• 使用能让变更更易于审阅的最精简结构。
• 将内部提示词或流程术语替换为具体行为。
• 更新 PR 时，根据当前完整差异重新撰写，不要叙述审阅历史。

标题

使用 <type>(<scope>): <subject> 或 <type>: <subject>。

允许的类型：feat、fix、ref、perf、docs、test、build、ci、chore、style、meta、license 和 revert。

• 使用最准确、最具体的类型和范围描述整个分支的主要变更。
• 只有当变更破坏外部契约时才使用 !，并在正文中说明受影响的部分。
• 避免使用 update、cleanup、misc、fix stuff 或 address feedback 等含糊的主题。结尾不要加句号。
• 只有现有标题仍能描述整个差异时，才保留它。

正文结构

选择最精简且有用的结构：

变更	内容
小型或显而易见的变更	用一个简洁段落说明，不加标题。
功能、错误修复或重构	说明变更的行为及影响；相关时补充根本原因、未变更的行为或不明显的实现方式。
契约变更或破坏性变更	说明受影响的 API、架构、载荷、配置、权限、存储或 CLI 部分；提供兼容性和迁移指导。
运维、视觉或工作流变更	相关时说明用户或运维人员受到的影响、衡量结果、故障模式或流程。
范围广泛、由生成产生或横跨多个部分的变更	说明组织原则、为何需要如此广泛的变更，以及审阅应从何处开始。

默认格式：

<What changed and what effect it has.>

<Why the approach, risk, migration, or review focus matters, if not obvious.>

针对审阅反馈的更新，应整体描述最终 PR，而不是按修订顺序叙述。

审阅辅助材料

只有在能减少审阅者还原变更所需的工作时，才使用辅助材料：

• 对变更的契约提供简洁的变更前后对比或接口示例。
• 对异步流程或状态转换提供简短的 Mermaid 图。
• 有视觉证据时，提供截图或录屏说明。
• 审阅者或采用者有需要时，提供发布、兼容性、风险或审阅顺序说明。

用一句话说明审阅者应关注材料中的什么内容。若正文更清楚，则省略材料。

边界

• 不要添加默认的 Summary、Changes 或 Test Plan 章节。
• 除非常规验证会改变风险评估或能说明有意义的回归覆盖，否则省略。对于文档、技能、文案或配置变更，默认省略验证内容。
• 不要粘贴命令、CI 日志、验证转储、提交日志、占位符或详尽的文件清单。
• 绝不要包含客户或组织名称、用户邮箱、支持工单内容、机密信息或个人身份信息。
• 仅在用户输入、分支名称、提交、PR 讨论或追踪器输出中确认过的问题引用时才使用。Fixes <issue> 会关闭问题；Refs <issue> 仅建立链接。

创建或更新

将新的 PR 创建为草稿。将正文写入临时 Markdown 文件，然后运行：

gh pr create --draft --title '<title>' --body-file /tmp/pr-body.md

使用 gh api 更新现有 PR：

gh api -X PATCH repos/{owner}/{repo}/pulls/PR_NUMBER \
  -f title='<title>' \
  -F body=@/tmp/pr-body.md

如果后续提交实质性地改变了范围、方案、破坏性行为、风险、迁移或评审预期，请更新标题和正文。仅涉及拼写错误、格式或重命名的后续提交无需更新。

示例

小型更改：

The AI Customizations section now starts collapsed so it does not consume
sidebar space before users need it. Expanding it preserves the existing saved
preference behavior.

破坏性契约变更：

Run logs now emit chunk-level records instead of one skill-level record.
Consumers that read top-level `findings` must iterate over
`chunk.findings` for each record.

Before:

```json
{"skill": "security-review", "findings": [...]}
```

After:

```json
{"schemaVersion": 1, "chunk": {"index": 1, "findings": [...]}}
```