pr-writer

PR Writer

将 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 表面；包括兼容性和迁移指南。
操作、视觉或工作流变更	用户/操作者影响、测量效果、故障模式或流程（如有用）。
广泛、生成或跨领域变更	组织原则、为何需要广泛性以及审查应从何处开始。

默认：

<变更了什么及其效果。>

<为什么方法、风险、迁移或审查重点重要，如果不明显的话。>

对于审查反馈更新，将生成的 PR 描述为一个整体，而不是修订序列。

审阅辅助

仅在减少审阅者重构工作时使用辅助：

• 对于变更的契约，提供紧凑的前后对比或接口示例。
• 对于异步流程或状态转换，提供小型 Mermaid 图。
• 当存在视觉证据时，提供截图或录制说明。
• 当审阅者或采用者需要时，提供发布、兼容性、风险或审查顺序说明。

用一句话介绍工件，说明审阅者应注意什么。当文字更清晰时省略它。

边界

• 不要添加默认的 Summary、Changes 或 Test Plan 部分。
• 省略常规验证，除非它改变风险评估或解释有意义的回归覆盖。对于文档、技能、文案或配置变更，默认省略。
• 不要粘贴命令、CI 日志、验证转储、提交日志、占位符或详尽的文件列表。
• 绝不包含客户或组织名称、用户电子邮件、支持工单内容、机密或 PII。
• 仅当从用户输入、分支名称、提交、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

当后续提交实质性改变范围、方法、破坏性行为、风险、迁移或审查期望时，刷新标题和正文。跳过仅拼写、格式和重命名的后续提交。

示例

小型变更：

AI 自定义部分现在默认折叠，因此不会在用户需要之前占用侧边栏空间。展开它保留现有的已保存偏好行为。

破坏性契约：

运行日志现在发出块级记录，而不是一个技能级记录。读取顶级 `findings` 的消费者必须遍历每个记录的 `chunk.findings`。

之前：

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

之后：

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