---
name: pr-dossier
description: 从代码改动生成完整的 Pull Request 描述（变更档案）：分析 diff 与提交历史，产出标题、摘要、背景动机、变更清单、影响面与测试说明。当用户要求为 PR 写描述、汇总改动、提交信息或变更说明时使用。Writes pull request descriptions from a diff.
whenToUse: 用户要求「为这个 PR 写描述」「总结这次改动」「生成提交信息」；或变更涉及多个文件、用户希望按统一结构描述时。
metadata:
  author: docgen
  version: "1.0.0"
  family: docgen
license: MIT
compatibility: 纯提示词技能，无需网络与第三方依赖；需要读取 git diff / 提交历史与变更文件的能力。
---

# pr-dossier：PR 描述生成

## 职责

把一次代码改动整理成一份「变更档案」（dossier）：让没有参与开发的人——同事、reviewer、未来的自己——只读描述就能理解这次改了什么、为什么改、有什么风险。本技能的核心原则是**描述可追溯到 diff**：描述里每一句话都要能在变更中找到依据。

## 何时使用

- 改动已完成（提交已存在或 diff 已生成），需要 PR 描述；
- 用户要求「总结这次改动」或「写提交信息」；
- 仓库有提交信息规范（如 Conventional Commits），需要按规范生成标题。

## 输入收集

| 证据 | 获取方式 | 用途 |
|---|---|---|
| 变更内容 | `git diff`（未提交）或 `git diff <base>..<head>` | 一切内容的依据 |
| 变更文件清单 | `git diff --stat`、`git status` | 规模判断、分组 |
| 提交历史 | `git log <base>..<head> --oneline` | 意图推断、避免遗漏 |
| 分支与上下文 | 当前分支名、关联 issue 号（如 PR 模板提到） | 背景动机 |
| 仓库规范 | 已有 PR 描述、CONTRIBUTING.md、commitlint 配置 | 结构对齐 |

## 工作流程

1. **读 diff**：先看 `--stat` 建立规模与影响面印象，再按文件通读实际改动。
2. **判定类型**：把改动归类——功能 / 修复 / 重构 / 性能 / 测试 / 文档 / 杂务（chore）——类型决定标题前缀与篇幅重点。
3. **还原意图**：结合提交信息和分支名，回答「这次改动解决什么问题」；提交信息缺失时从代码注释和改动本身推断。
4. **按区域分组**：把改动按模块/文件分组，每组一句话概括「改了什么、为什么这么改」，避免逐行复述。
5. **评估影响与风险**：从改动的调用链判断受影响模块、行为变化、破坏性变更。
6. **起草与核验**：按下方模板输出，然后逐条核对「这句话在 diff 里有没有依据」。

## 输出模板与变量

```markdown
## {pr_title}

### 摘要
{summary}

### 背景与动机
{motivation}

### 变更内容
{changes_by_area}

### 影响面与风险
{impact_and_risks}

### 测试与验证
{testing}

### 关联信息
{related_issues}

### 备注
{notes}
```

| 模板变量 | 含义 | 示例 |
|---|---|---|
| {pr_title} | 标题：类型(范围): 一句话概括。类型与仓库规范对齐，无规范时默认 feat/fix/refactor/perf/test/docs/chore/breaking | `feat(skills): 新增 changelog 生成技能` |
| {summary} | 2-4 句摘要：改了什么、达到什么效果 | … |
| {motivation} | 背景：为什么需要这次改动（问题、需求、约束） | 手动维护 changelog 易遗漏，改为从 git 历史自动生成 |
| {changes_by_area} | 按模块/文件分组的变更清单，每组一行到数行 | - `skills/changelog-curator/`：新增技能本体 |
| {impact_and_risks} | 受影响模块、行为变化、风险点；无风险写「无预期破坏性变更」 | 影响现有 README 生成流程；新增变量不破坏旧模板 |
| {testing} | 测试方式：已跑的命令、覆盖的行为、未覆盖的已知缺口 | `python -m unittest`，覆盖 frontmatter 解析 |
| {related_issues} | 关联 issue / PR 编号，没有则省略此节 | Closes #42 |
| {notes} | 破坏性变更、迁移说明、待办、截图占位；没有则省略 | 破坏性变更：SKILL.md 的 metadata 需加引号 |

## 风格选项

默认语言跟随用户提问语言，篇幅为标准。用户可用自然语言覆盖：

- 语言：`语言=简体中文`、`language=en`
- 篇幅：`篇幅=精简`（只保留标题、摘要、变更内容三部分）、`篇幅=标准`（默认）、`篇幅=详尽`（补充逐文件说明）
- 语气：`语气=正式`（默认，客观陈述）、`语气=平实`（口语化，适合团队内部）

## 质量检查清单

输出前逐项自检：

- [ ] 标题符合仓库提交规范（或默认规范），类型与改动真实匹配
- [ ] 变更内容覆盖 diff 中的每一个有意义的改动，没有遗漏也没有复述每个字符
- [ ] 背景动机能回答「为什么改」而不是只描述「改了啥」
- [ ] 影响面来自真实调用关系，破坏性变更被显式标注
- [ ] 测试部分只写真实存在的命令或已验证的行为，不写「已测试」
- [ ] 关联 issue 编号与用户提供的信息一致
- [ ] 没有把 diff 之外的猜测写成事实（未证实的推断用「可能」「疑似」）

## 不要做

- 不要逐行翻译 diff——那是机器输出，不是描述
- 不要编造测试结果、性能数据、兼容性承诺
- 不要忽略删除与重构：删除代码和改动签名同样是重要信息
- 不要在标题里堆砌多个类型（如 feat+fix+chore）；按主要意图取一个

## 边界情况

- **diff 为空**：提示用户没有可描述的变更，不产出空模板。
- **巨型 diff**：按「公共接口与行为变化优先」原则概述，重点标注高风险文件；主动建议 reviewer 关注范围。
- **WIP / 草稿 PR**：描述中显式标注未完成部分，不给完整测试承诺。
- **提交信息杂乱但完整**：以 diff 本身为准，提交信息只用于推断意图。
- **有 PR 模板**：输出按仓库模板的结构组织（本模板与仓库模板冲突时以仓库模板为准，保留本技能的变量填充方式）。
