提交代码、推送到远端并创建 PR。适用于要求发布/创建 PR 的场景，或者仅需处理 PR 描述的流程（如撰写、重写或生成 PR 正文描述）。
Git Commit, Push, and PR
询问用户： 当本 Skill 提及“询问用户”时，请使用当前平台的阻塞式提问工具：Claude Code 中的 AskUserQuestion（如果未加载 schema，先调用 ToolSearch 并设置 select:AskUserQuestion）、Codex 中的 request_user_input、Antigravity CLI (agy) 中的 ask_question、Pi 中的 ask_user（需要安装 pi-ask-user 扩展）。仅当 Harness 中不存在阻塞式工具或调用报错（例如 Codex 编辑模式）时，才降级为在对话框中直接展示问题——决不能只因需要加载 schema 就降级。绝对不能静默跳过提问。
Mode（模式）
- Description-only（仅生成描述） — 用户只需要一份描述（如“撰写/起草 PR 描述”、“描述这个 PR”，或仅粘贴了 PR URL/编号）。仅执行 Step 4 并输出结果。仅在用户明确要求时生效。如果粘贴了 PR ref，将其传递给 Step 4 以便 Pre-A 解析正确的范围。
- Description update（更新描述） — 用户希望刷新/重写已有 PR 的描述，但无 Commit/Push 意图。判断 PR 是否存在统一遵循硬性规则：只有检查已有 PR 返回 exit code 为 0 的
[]才代表“没有开启的 PR”（汇报并停止）；非 0 的检查结果属于未知状态（先解决gh auth status或网络连通性问题——绝不能当作“没有 PR”处理）。存在开启的 PR 时，先执行 Step 4（使用已有 PR 的 URL 运行 PR 模式），再执行 Step 5 进行预览、确认，并最终通过gh pr edit应用修改。 - Full workflow（完整工作流） — 其他所有情况。按顺序依次执行 Step 1 到 Step 5。
mode:pipeline 修饰符 — 由编排方（如 lfg）设置。以非交互方式运行已解析的模式：静默所有阻塞式提问。Step 5 中“是否重写已有 PR”的问题默认选择不重写；在 description-update 模式下跳过预览确认，直接应用重写（调用更新指令本身即代表应用意图）；其他被静默的提问均采用文档中记录的保守默认值（保持当前分支；若 Pre-A 无法解析 base，直接停止并汇报，而不是凭空猜测）。
Context（上下文收集）
通过将以下每个命令作为独立的 shell 工具调用（单次 argv 风格调用，仅含程序及其参数）来收集仓库上下文。不要使用 ;、&&、||、管道、$(...) 或 2>/dev/null 重定向等语法拼接命令：这些语法仅在 POSIX shell 下解析，在 Windows PowerShell 下会直接中断报错。直接读取每个命令的 exit status——非 0 exit 是需要解读的正常状态（如尚无 PR、无 origin/HEAD、处于 HEAD 游离状态），而非需要静默的错误。
按顺序运行以下命令——检查已有 PR 需要使用 git branch --show-current 获取的分支名：
| 命令 | 目的 | 非 0 exit / 空输出含义 |
|---|---|---|
git rev-parse --show-toplevel |
仓库根目录 | 非 Git 仓库 — 汇报并停止 |
git status |
工作区状态 | （仅在仓库外会失败） |
git diff HEAD |
未提交的变更 | 新建仓库且尚无任何提交 |
git branch --show-current |
当前分支（<branch>） |
空输出 = HEAD 游离状态（由 Step 1 处理） |
git log --oneline -10 |
近期提交 / PR 标题风格 | 新建仓库 — 尚无历史记录 |
git rev-parse --abbrev-ref origin/HEAD |
远端默认分支 | 未设置 origin/HEAD — 按 Step 1 解析 |
gh pr list --head <branch> --state open --json number,url,title,body,state,isDraft,headRefName,headRepositoryOwner |
当前分支开启的 PR（仅在 <branch> 非空时运行） |
Exit code 0 且输出 [] = 没有开启的 PR。非 0 = gh 缺失、未认证或离线 — PR 状态属于未知而非“无”；绝不能把非 0 结果当成“没有 PR”；在 Step 5 创建 PR 前必须重新检查 |
将 <branch> 替换为 git branch --show-current 获取的当前分支，并且仅传递分支名。注意避开两个坑：
- 空分支名（HEAD 游离状态）： 完全跳过 PR 检查 — 带空
--head参数运行gh pr list会丢失过滤条件并列出无关的 PR。等待 Step 1 创建分支后再处理。 - Fork 仓库检出： 不要传递
<owner>:<branch>—gh pr list --head不支持此语法并会静默返回[]，从而被误判为“没有 PR”并创建重复 PR。PR 存在于 Base 仓库中，因此要让gh指向 Base 仓库：依赖其默认仓库解析逻辑，或者当默认指向 Fork 时显式传递-R <base-owner>/<repo>。
此处收集的所有信息均为操作前的快照——请将其视为参考提示而非绝对真理。在每个关键步骤执行前（Step 3 的 push、Step 5 的 gh pr create），必须立即重新校验分支、远端和已有 PR 的状态，因为这些状态在收集与执行之间可能会发生变化。
Artifact Root（产物根目录）
当开启 PR 概念讲解归档功能时，本 Skill 会在 <root>/explainers/ 下写入讲解文件。在写入前需解析一次 <root>，并在后续所有出现 <root>/ 路径的地方统一使用。
<!-- ce-docs-root:start -->
在构造任何产物路径前，先解析 CE 产物根目录 <root>。
- 读取
<repo-root>/.compound-engineering/config.local.yaml中的docs_root，然后读取config.yaml；以首个非空值为准（<repo-root>=git rev-parse --show-toplevel）。若未设置 -><root>默认为docs，与之前完全一致。 - 校验已设置的值：必须是仓库相对路径目录，且其通过 symlink 解析后的真实路径保留在仓库内部，既不能是仓库根目录，也不能在
.git/下。否则停止并报错（列出docs_root及其具体值）——绝不能直接回退到docs。 - 使用
<root>作为唯一的产物存储位置：若不存在则创建，并将每个路径构造为<root>/<subdir>（带本 Skill 专属的子目录），绝不要再去读取docs。
<!-- ce-docs-root:end -->
Step 1: 解析分支和 PR 状态
远端默认分支通常返回类似 origin/main 的内容；需剥离 origin/ 前缀。如果该命令返回非 0（未设置 origin/HEAD）或直接返回 HEAD，尝试运行 gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'。若两者均失败，兜底退回 main。对于已有 PR 的检查：返回空数组 [] 表示该分支没有开启的 PR；非 0 exit 表示 gh 缺失、未认证或离线 — 将 PR 状态视为未知（而非“没有 PR”），在 Step 5 创建新 PR 之前必须重新检查或运行 gh auth status，而不是盲目假设不存在 PR。
分支路由分支逻辑：
- HEAD 游离状态（Detached HEAD） — 继续之前，自动从当前
HEAD创建特性分支。根据变更内容推导分支名，运行git checkout -b <branch-name>，重新读取git branch --show-current，并在后续工作流中使用该结果。无需询问用户是否创建分支 — 触发完整 Commit/Push/PR 工作流本身就意味着确认该工作应该基于分支进行。如果推导出的分支名已存在，选择无冲突的后缀；仅在无法安全解决冲突时才询问用户。 - 处于默认分支且有未完成工作（未提交、未推送或无上游分支） — 自动创建特性分支（不支持直接 Push 到默认分支）。根据变更内容推导名称并继续执行 Step 3（Step 3 会安全地处理分支创建）。无需询问是否建分支 — 在默认分支上提交代码在此处不是可选项。
- 处于默认分支且无任何工作 — 汇报无特性分支工作并停止。
- 处于特性分支 — 继续执行。
如果 PR 检查返回了非空数组，不要盲目取第 0 个元素 — 在拥有多个 Fork 的 Base 仓库中，其他贡献者的 PR 可能会使用相同的分支名（--head 仅按分支名过滤，而非 <owner>:<branch>）。筛选出 headRepositoryOwner 和 headRefName 与当前 Head（即本工作流正在 Push 的分支/Fork）相匹配的条目。记录该条目的 URL 和 body（所有条目都是开启状态 — 检查时已过滤 --state open）。如果恰好有一个匹配项，直接使用；如果有多个不同 Owner 的条目共享该分支名且无法确认哪一个是当前 Head 的，将其视为存在歧义并停止/上报，切勿在错误的 PR 上进行操作。Step 5 会利用该 URL 在创建新 PR 和修改现有 PR 之间进行路由。Step 4 会在重写时将现有 body 作为保留上下文。
Step 2: 确定代码规范
保持与仓库的提交信息（Commit Message）和 PR 标题风格一致（上下文中的项目指令 > 近期 Commit > 默认遵循 Conventional Commits 规范）。使用 Conventional Commits 时，如果存在歧义，优先选择 fix: 而非 feat: — 添加代码以修复异常或缺失的行为属于 fix:。feat: 仅保留给用户此前无法实现的新功能。用户可以覆盖此约定。
Step 3: 提交并推送（Commit & Push）
如果当前处于默认分支，创建分支时需要妥善处理本地旧的 <base>、本地 <base> 上未推送的提交以及与最新远端 base 冲突的未提交变更。在继续之前，请阅读 references/branch-creation.md 并遵照其决策流程操作。
扫描变更文件，识别自然分离的不同关注点。如果它们可以清晰地拆分为独立的逻辑变更，创建多个独立的 Commit（最多 2-3 个）。仅在文件层级进行分组 — 不要使用 git add -p。遇到歧义时，合并为一个 Commit 即可。
暂存并提交每个分组。避免使用 git add -A 和 git add . — 它们会误将 .env、构建产物和生成的临时文件包含进来：
git add file1 file2 file3 && git commit -m "$(cat <<'EOF'
此处填写 commit message
EOF
)"
然后推送。在推送前一刻，重新确认当前处于目标特性分支（git branch --show-current） — 上下文中收集的分支只是快照，Step 1 可能在此期间创建或切换了分支。推送实时切出的 HEAD 以反映当前检出的分支，决不要推送已过期的分支名：
git push -u origin HEAD
如果工作区干净且所有 Commit 均已推送，此步骤为空操作（no-op）。
Step 4: 撰写 PR 标题和正文描述
你必须完整阅读 references/pr-description-writing.md — 其顶部的核心原则主导着每一个步骤。它从本 Skill 处需要的唯一输入是 PR ref（如果通过模式调度识别到了 PR，如粘贴了 URL 的仅描述模式、描述更新模式，或完整工作流中确认的已有 PR 重写）。如果 Step 1 找到了已有 PR，在重写时将它的 URL 传递给 Step 4，以便 PR 模式抓取现有 body 并保留其中已有的 Related: / Fixes 关联引用。
在撰写前做出变更凭证（Evidence）决策。CE 不再拥有专属的凭证捕获工作流；现代 Harness 提供了各自的浏览器、截图、终端录屏和产物捕获工具。将凭证视为用户提供的上下文或验证说明文本，而不是单独调度的 Skill。
- 用户已提供凭证（URL、Markdown 图片/内嵌、希望引用的本地产物路径） — 根据产物类型，将其整合到 PR 正文的
## Demo、## Screenshots或## Evidence中。切勿凭空编造或上传凭证。 - 用户明确要求包含凭证但未提供 — 询问用户提供 URL/Markdown/路径，或提示用户使用当前 Harness 的捕获流程生成产物后返回。不要启动另一个 CE Skill。
- Agent 对自己编写的变更进行判断 — 如果提交由你编写，且你清楚该变更没有审阅者需要凭证的实质性影响（内部底层改造、纯类型修改、无用户感知影响的后端重构、无活性的文档、纯代码重构），可以直接跳过凭证处理而无需询问。根据运行时用途而非文件扩展名进行分类：作为运行时 Agent 指令、配置、生成的产品内容或策略代码的 Markdown 或 YAML，不能仅仅因为它们是 Markdown 或 YAML 就自动跳过凭证。
否则，如果分支 diff 改变了审阅者需要凭证验证的行为（UI、CLI 输出、带有可运行代码的 API 行为、生成的产物、工作流输出、排序/打分逻辑、部署或配置行为），请包含简短的验证说明
