pr-prep

拉取请求准备工作流

不要使用的情况

• 审查他人的 PR（使用 sanctum:pr-review）
• 只需要提交说明（使用 sanctum:commit-messages）

用法

使用此技能暂存更改并生成 PR 摘要。先运行 Skill(sanctum:git-workspace-review)，以记录仓库状态和差异。

必需的进度跟踪

开始前，为以下步骤创建进度项：

1. pr-prep:workspace-reviewed
2. pr-prep:quality-gates
3. pr-prep:self-reviewed
4. pr-prep:changes-summarized
5. pr-prep:testing-documented
6. pr-prep:pr-drafted
7. pr-prep:content-verified

每完成一个部分，就将对应项标记为完成。

步骤 1：审查工作区（workspace-reviewed）

确认 Skill(sanctum:git-workspace-review) 已完成。如果初次审查后暂存了更改，请重新执行该技能以刷新上下文。

步骤 2：运行质量门禁（quality-gates）

使用项目特定的命令执行格式化、代码检查和测试 （例如，make lint、make test）。继续之前解决所有失败。 如果无法在本地执行某项任务，请记录原因 以及已执行的替代验证。特定语言的命令 和失败处理详见 modules/quality-gates.md。

同步功能参考文档

如果任何插件文件发生更改（plugin.json、技能、命令、 Agent 或钩子），请运行 make docs-sync-check，验证 book/src/reference/capabilities-reference.md 是否为最新。 如果报告不一致，请运行 /sync-capabilities --fix 或手动更新参考文档后再继续。

步骤 2.5：自我审查（self-reviewed）

像第一次审查这些更改的审查者一样阅读差异。这能在其他人花时间审查前发现范围蔓延、过时的调试代码 以及不明确的更改。

自动化检查：

# Check for debug statements left in
git diff --cached --name-only | xargs grep -nE \
  '(console\.log|print\(|debugger|TODO|FIXME|HACK|XXX)' \
  2>/dev/null || true

# Check for commented-out code blocks (3+ consecutive lines)
git diff --cached | grep -c '^+.*//.*[a-zA-Z]' || true

# Check for formatting-only commits mixed with feature work
git log --oneline $(git merge-base HEAD origin/master)..HEAD | \
  grep -iE '(fmt|format|lint|style|whitespace)' || true

增量偏差审计：

运行 Skill(imbue:justify)，计算增量偏差分数 并检查是否符合铁律。如果分数达到 YELLOW 或更高， 请在继续前说明每个被标记信号的理由。如果为 RED 或 STOP，请重新考虑处理方式。

手动验证：

• 阅读完整差异：每项更改是否都服务于 既定目标？
• 未遗留调试语句或 TODO 标记
• 没有已注释掉的代码块
• 没有将格式更改与逻辑更改混在一起
• 没有应该压缩的修正提交
• 增量偏差分数为 GREEN，或已说明 YELLOW 的理由
• 符合铁律：PASS（未篡改测试）

如果发现问题，请先修复再继续。

步骤 3：总结更改（changes-summarized）

从分析器入手，而不是重新阅读差异：

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/pr_prep_analyze.py" --base origin/main

它会读取分支中已更改的文件和提交，将文件分类为 功能、测试、文档及其他，标记提交主题中的任何 ! 破坏性更改标记， 根据已更改文件列表报告它能判断的质量门禁（是否涉及测试、是否涉及文档、是否描述更改）， 推荐合并策略，并打印说明模板。传入 --reviewer-map <json> 可将路径前缀映射到审查者；传入 --json 可将其作为数据使用。

门禁显示为 unknown（JSON 中为 null）表示脚本未进行评估：它不会运行测试、代码检查或类型检查，也不会做出发布决策，因此 passes_checks 和 includes_breaking_changes 始终会显示为 unknown。应将 unknown 视为“你必须自行检查”， 绝不能视为通过。passes_checks 的判断由步骤 2 负责。

然后结合工作区审查的笔记和分析器的分类，找出差异中的关键点，并将其归纳为 2–4 段，说明技术更改及其理由。注明破坏性更改、迁移或文档更新。

第 4 步：记录测试（testing-documented）

列出执行的每条测试命令及其结果。如果跳过了测试，请记录原因和缓解计划。

符合以下任一条件时，附上手动测试计划：

• 此更改没有自动化测试覆盖。
• 此更改影响面向用户或命令行的流程。
• 此更改是错误修复。提供复现、修复和验证步骤，其中复现步骤在父提交上会失败。
• 此更改修改了外部契约。

将其写成编号步骤，并在每一步说明预期结果。没有预期结果的步骤，评审者就无法判定其是否失败。格式和示例见 modules/pr-template.md。

第 5 步：起草 PR（pr-drafted）

先填写模板中的事实表（Who、Where、When），再填写 Why 和 What-and-how 部分，然后填写 Test plan 和 Checklist。标题使用祈使语气，且应自成一体，确保脱离上下文阅读 git log 时仍然通顺。

每个 PR 都要填写表格的全部三行。不适用的行应明确注明（例如 External: none、on merge），而不是直接删除，这样读者才能区分被省略的影响范围与完全没有影响范围。

根据更改内容添加 issue 引用、截图、迁移指南或后续事项。模板结构、完整示例和不同篇幅的示例见 modules/pr-template.md。关于此结构的决策及其来源记录在 docs/adr/0021-pr-descriptions-in-two-registers.md 中。

第 6 步：验证内容质量（content-verified）

按照 Skill(scribe:slop-detector) 的原则检查草稿。确认 PR 描述不含一级劣质措辞（delve、comprehensive、leverage、utilize、robust、seamless），也不含 “I'd be happy to” 或 “It should be noted” 这类公式化短语。确保文本中没有 AI 署名，且所有说法都有命令、数字或文件名等证据支撑。使用主动语态，并通过正文提供上下文，保持结构均衡。

词汇替换

• 将 leverage 或 utilize 替换为 use。
• 将 comprehensive 替换为 thorough 或 complete。
• 将 robust 替换为 solid 或 reliable。
• 将 facilitate 替换为 help 或 enable。
• 将 streamline 替换为 simplify。

修正

如果描述中存在劣质内容，请按照 Skill(scribe:doc-generator) 的原则，用具体信息支撑说法，删除营销措辞，并使用直接陈述。

输出说明

将最终 PR 描述写入指定路径，然后显示文件路径及其内容以供确认。

备注

不要在 PR 文本中注明工具或 AI 署名。如果需要在过程中修改内容，请重新运行质量检查。本技能涵盖准备工作；推送更改和创建 PR 不属于此工作流。

支持模块

• 进度项模式 - sanctum 进度项的命名约定

故障排查

如果 make 或 npm 等项目专用命令不可用，请根据 README 检查环境设置。遇到权限错误时，请检查是否有权写入构建目录。如果某一步失败且没有清晰的输出，请使用详细标志重新运行命令以查看日志。

完成标准

• 在技能宣布完成之前，所有 7 个进度项（pr-prep:workspace-reviewed 至 pr-prep:content-verified）都已标记为完成
• 已运行并通过质量门禁（格式检查、lint、测试）；如有失败，必须修复后才能继续，不能跳过
• 分析器输出为 unknown 的每项门禁都已人工判定，因为 unknown 表示未对其进行任何评估：脚本不会运行测试、lint 或类型检查，因此 passes_checks 和 includes_breaking_changes 始终会显示为该状态
• PR 描述文件已写入指定路径，且其内容已显示以供确认
• 已包含事实表格，且其中三行（Who、Where、When）均已填写，包括 Where 中的 External: 部分
• Why 部分以某个问题、数字或事件为依据，而非泛泛而谈
• 第 4 步中的四项触发条件有任一满足时，均已附上手动测试计划，且每个步骤都注明了预期结果
• imbue:justify 的附加偏差评分为 GREEN；或为 YELLOW，且已明确说明每个被标记的信号
• PR 描述中不含任何一级禁用词（delve、comprehensive、leverage、robust、seamless 等）