incu-way-prepare-pr

准备 PR / 提交更改

这是 incu-way 工作持久化到 git 的唯一入口。本仓库中的其他所有流程都只会写入文件，并在自然检查点建议运行此技能——它们不会自行提交、推送或创建 PR。这里有意不逐一列出这些流程：任何当前或未来的 incu-way 流程都遵循同一规则，因此添加、重命名或移除技能时，无需同步更新任何内容。

防止自行调用的真正关卡是上方的 frontmatter description，而不是本段文字——技能匹配会在读取正文之前根据该描述进行，因此“仅在用户明确要求时调用”必须写在其中才能真正生效。本段正文是第二道防线，供直接阅读此文件的人参考：如果你是调用方技能，请勿自行调用此技能——请说类似 “此检查点已准备就绪。想要提交时，请运行 incu-way-prepare-pr（或让我来运行）。” 的话，然后到此为止。

---

步骤 1 — 查找上下文

git branch --show-current

按照各流程相同的方式推导 {slug}（分支名去掉 feat/ | fix/ | fix/security- | chore/ | docs/ | assess/ 前缀）。如果 .ways/state.json 存在，请读取它 （暂时不要写入），以了解此检查点对应的 flow、phase 以及关卡 / 文档。如果文件不存在 （例如，没有条目文件的评估 / 文档流程，或普通的临时“提交此内容”请求），则无需读取，继续操作。

步骤 2 — 准确展示将要提交的内容

git status --short
git diff --stat
git diff --stat --staged

在进行任何操作之前，先向用户展示这些内容。如果没有暂存或更改的内容，请告知用户并停止——没有内容需要提交。

第 3 步 — 提议提交信息

每次提交都必须遵循 Conventional Commits， 没有例外：

<type>(<scope>)<!>: <description>

<body>

<footer>

type — 从 feat、fix、docs、style、refactor、perf、test、build、ci、 chore、revert 中选择。这份确切列表是 Incu 组织政策，并非 Conventional Commits 规范本身（规范只定义了 feat/fix 的语义，并未限定类型集合）。这项政策旨在让所有 incu-tech 仓库的历史记录都便于检索且保持一致：仓库不会使用此列表之外的专属类型，应选择 最接近的类型（通常是 chore），而不是另造一种类型。不要猜测：调用流程自己的 SKILL.md 已经记录了该阶段的提交信息格式（在用户当前所处检查点附近查找“commit message format” / “suggested commit message”部分），也可以根据分支前缀推断：

分支前缀	type	scope
feat/{slug}	feat	{slug}
fix/{slug}	fix	{slug}
fix/security-{slug}	fix	security
chore/{slug}	chore	{slug}（若涉及整个仓库，则省略，例如版本升级涉及每个文件）
docs/{slug}	docs	{slug}
assess/{slug}	docs	{slug}（评估／威胁建模／安全验证报告属于文档——绝不要另造 assess: 这类非标准类型）

如果分支前缀和调用流程自己的格式说明都无法明确类型，请询问用户，不要猜测。

description — 使用祈使语气（用 “add”，而不是 “added”/“adds”），冒号后立即使用小写字母， 末尾不加句号，长度应足够短，使整行 type(scope): description 不超过约 72 列。它说明改了什么； 正文说明为什么。

! — 仅当此提交会破坏已记录的契约时，才紧跟在 scope 后（若没有 scope，则紧跟在 type 后）； 例如 schema、公开 CLI 标志、磁盘上的格式，或下游使用方所依赖的任何内容。必须始终附带 BREAKING CHANGE: 页脚，说明哪些内容会受影响以及如何适配——二者不可缺一，也绝不可用于 没有外部可见破坏的内部重构。

正文 — 描述后空一行，然后撰写约 72 列换行的文字。 说明仅凭 diff 无法看出的原因：为何选择这种方案而非其他方案、它取代了什么，以及审阅者需要了解 哪些代码中不明显的信息。正文绝不能逐行复述 diff；如果改动很小，描述已足以说明一切，正文可省略 （例如，一行拼写错误修复不需要正文）。

页脚 — 正文后空一行：对于已解决或相关的问题，添加 Closes #123 / Refs #123 （仅当此仓库中确实存在相应问题时使用——绝不要捏造编号）；如果上文使用了 !，则添加 BREAKING CHANGE: <description>。

原子性。 每次提交只包含一个逻辑改动——每次提交都应能独立构建并通过自己的测试／评估， 这样将来执行 git bisect 或仅回滚此提交时，不会连带引入无关改动。如果状态文件 .ways/state.json 与其他文件一同更改，它应与这些文件一并提交（它是关于同一改动的元数据， 而非单独的改动）——但如果暂存区／工作区中有多个互不相关的逻辑工作单元（例如两个无关的检查点， 或随一个无关功能一起搭载的顺手重构），请指出这一点，并建议拆分为多个提交，而不是默默地将它们打包在一起。

提交确认关卡

请说："即将提交：{file list}。提交信息：{proposed message}。在我运行 git add / git commit 前请先确认。"

停止。在用户确认之前，不要运行 git add 或 git commit。

只有在用户明确确认后，才暂存已审核的文件，并进行提交。

第 4 步 — 推送并创建 PR（仅当用户也要求这样做时）

不要假设用户希望提交代码就意味着也要推送或创建 PR。请询问：

你还希望我推送 {branch} 并向 {base} 创建 PR 吗？

如果用户同意，请使用调用流程为 PR 阶段定义的相同模板起草标题和正文（摘要、相关文档链接、验证清单等——具体正文格式请参阅该流程自身的 SKILL.md）。向用户展示起草的标题和正文。

PR 标题必须符合 Conventional Commits 格式（type(scope): description，规则与第 3 步相同）——这里的大多数仓库都使用压缩合并，因此标题会成为永久提交消息。如果分支包含多个类型各异的提交，请选择最能体现 PR 核心内容的变更类型（通常是最后一个、最重要的类型），而不是只看第一个提交。

公开仓库内容检查（起草正文前）

检查 {base} 所属的仓库是否公开：gh repo view {owner}/{repo} --json isPrivate -q .isPrivate。如果检查结果表明仓库公开，或者检查无法运行，都应将其视为公开仓库——绝不能默认仓库是私有的。

如果仓库公开，标题、正文、分支名和提交消息中绝不能包含：

• 任何人的姓名、用户名或姓名缩写——无论是报告者、审阅者，还是内部对话中提及的任何人。
• 内部频道（包括 Slack 等平台）的名称，或与该频道相关的日期。
• 内部对话（Slack、会议、私信）中的逐字引述或近似转述。

保留技术实质——发生了什么问题、原因是什么、做了哪些修改、如何验证——但不要提及来源（例如“内部报告”“在实际使用中发现”）。

**此检查涵盖整个待推送差异，不仅是 PR 文本。**运行 git diff {base}...{branch} --name-only，并检查此 PR 实际新增或修改的每个文件，而不仅仅是 PR 正文、分支名或提交消息。如果此 PR 新增或修改的文档（例如 BUG.md 中的 Context、PRD 中的需求记录等）提到了某人或引用了内部讨论，那么该内容会在 PR 合并时进入公开仓库。把内容“留在文档里”并不能起到保护作用，因为文档会成为公开差异的一部分。创建 PR 前，请对该文档进行清理（删除姓名、频道名和引述，并像 PR 正文一样改用不提及来源的表述），不要只避免在 PR 文本中重复这些内容。

如果提到某人的文档已在更早的 PR 或提交中进入仓库，且本 PR 的差异并未涉及该文档，则不属于此处的检查范围。此检查针对本 PR 将要公开的内容，而不是对整个仓库的历史进行追溯审查。

如果仓库是私有的，则这些要求均不适用——按通常方式撰写 PR。

门槛 — 确认推送和创建 PR

请说：“即将推送 {branch} 并创建 PR：{base} ← {branch}，标题为 {title}。请确认后，我再推送并创建 PR。”

停止。未得到用户确认前，不要运行 git push 或 gh pr create。

只有在用户明确确认后：

git push -u origin {branch}
gh pr create --base {base} --head {branch} --title "{title}" --body "{body}"

将生成的 PR URL 告知用户。

第 5 步 — 更新状态（如果存在状态文件）

如果 .ways/state.json 存在，且刚刚创建了 PR，请将对应的 gates[].url 设为 PR 链接，作为第 4 步中已确认工作的一部分——这是对刚执行操作的元数据记录，不是新的、未经告知的操作，因此不需要单独设置门槛。如果 PR 门槛现在应标记为 passed（例如，PR 已在外部合并，而用户只是在此处记录这一状态），也请更新其 status。

不要做的事

• 不要在其他技能的工作流中自动调用自己——只有用户在当前轮次明确提出请求时，你才运行。
• 未经上述确认关卡的明确确认，不要提交、更改推送或开启 PR，即使用户直接调用了你也不例外——调用此技能只是开始对话，并不等同于确认。
• 不要在一个提交中捆绑无关更改，除非事先说明。
• 不要合并 PR。开启 PR 属于此技能的范围；合并始终是此技能之外需要用户单独明确执行的操作。