完成 GitHub Issue 实现后，用 gh CLI…

当某个 GitHub Issue 的代码实现已完成，需要按标准流程提交、推送、创建 PR、合入、关闭 Issue 并回写实现总结时使用。

适用场景

解决思路

1. Step 1 提交代码：运行 git status 检查变更状态；运行 git diff --stat HEAD 查看变更统计。
2. Step 1 提交代码：用 git add <files related to this issue> 只暂存当前 Issue 相关的文件，不要 add 不相关的文件。
3. Step 1 提交代码：用 git commit -m "$(cat <<'EOF' {简要描述} (#issue-number) {可选的详细说明} EOF )" 提交，commit message 中包含 #issue-number 以关联 Issue。
4. Step 1 关键规则：commit message 中包含 #issue-number 以关联 Issue。
5. Step 1 关键规则：只暂存当前 Issue 相关的文件，不要混入其他变更。
6. Step 2 推送分支：如果还在 main/master 上，先创建功能分支：git checkout -b {branch-name}；如已在功能分支则跳过。
7. Step 2 推送分支：运行 git push -u origin {branch-name} 推送到远程。
8. Step 2 分支命名建议：使用 feat/issue-42-short-desc 或 fix/issue-42-short-desc。
9. Step 3 创建 PR：用 gh pr create --title "{简要描述}" --body "$(cat <<'EOF' ## Summary - 实现内容概述 Closes #{issue-number} ## Test plan - [ ] 测试项 1 - [ ] 测试项 2 EOF )" 创建 PR。
10. Step 3 关键规则：PR body 中写 Closes #N 或 Fixes #N，合入后 GitHub 自动关闭 Issue。
11. Step 3 关键规则：PR title 简洁，不超过 70 字符。
12. Step 4 合入 PR：先运行 gh pr checks 查看 PR 状态并确认 checks 通过。
13. Step 4 合入 PR：运行 gh pr merge --squash --delete-branch 合入；默认 merge commit，可选 --squash 或 --rebase。
14. Step 4 参数说明：--squash 压缩为单个 commit 合入（推荐）；--rebase 执行 rebase 合入；--merge 使用普通 merge commit；--delete-branch 合入后删除远程分支。
15. Step 5 添加实现总结评论：PR 合入 / Issue 关闭时，始终在 Issue 上添加实现总结评论，方便后续直接从 Issue 回溯设计决策与代码变更。
16. Step 5 添加实现总结评论：运行 gh issue comment {issue-number} --body "$(cat <<'EOF' ... EOF )" 添加评论。
17. Step 5 评论结构：以 ## 实现总结 开头，包含 **核心变更**：从 PR body Summary 提取的实现摘要，3-5 条 bullet。
18. Step 5 评论结构：包含 **实现亮点（Highlights）**：值得强调的技术亮点（性能优化、优雅设计、复用抽象、关键测试覆盖等），或 None。
19. Step 5 评论结构：包含 **设计决策（Design Decisions）**：spec 模糊/未定处所做的选择及理由，或 None。
20. Step 5 评论结构：包含 **偏离（Deviations）**：有意偏离 spec 之处：spec 怎么说 → 实际怎么做 → 为什么，或 None。
21. Step 5 评论结构：包含 **权衡（Tradeoffs）**：考虑过的备选方案及最终选择的原因，或 None。
22. Step 5 评论结构：包含 **待确认（Open Questions）**：需用户确认的假设或后续跟进项，或 None。
23. Step 5 评论结构：末尾附加 **PR**: #{pr-number} 和 **Commit**: {hash}，方便直接跳转。
24. Step 5 关键规则：无论是 auto-close 还是手动 close，都必须添加此评论。
25. Step 5 关键规则：参考 note-it 的四类结构（设计决策 / 偏离 / 权衡 / 待确认）；某类无内容写 None 并简要说明。
26. Step 5 关键规则：「实现亮点」提炼本次实现最值得关注的技术点（性能、设计、复用、测试等），无则写 None。
27. Step 5 关键规则：核心变更从 PR body 的 Summary 部分提取，保持简洁（3-5 条 bullet）。
28. Step 5 关键规则：附加 PR 编号和 commit hash，方便直接跳转。
29. Step 5 关键规则：若已通过 /note-it 生成 docs/issue#XXXX.html，可直接复用其四类内容，并在末尾附上该文件链接。
30. Step 6 手动关闭 Issue：如果 PR body 中已写 Closes #N，合入后 Issue 会自动关闭，跳过此步。
31. Step 6 手动关闭 Issue：否则运行 gh issue close {issue-number} --reason completed 手动关闭。
32. 错误处理：gh pr checks 有失败项时，查看失败原因，修复后追加 commit 推送。
33. 错误处理：PR 有 merge conflict 时，运行 git fetch origin main && git rebase origin/main，解决冲突后 force push。
34. 错误处理：gh pr merge 被 branch protection 阻止时，确认 required reviews 已满足，或请 reviewer approve。
35. 错误处理：Issue 合入后未自动关闭时，确认 PR body 包含 Closes #N，或执行 Step 6 手动 gh issue close。
36. 完整示例收尾：合入并添加评论后，运行 git checkout main；git pull 切回主分支并拉取最新代码。

适用边界 · 注意事项

• 尚未安装或未登录 gh CLI（gh auth status 不可用）、仓库不是 GitHub、或没有权限合入/关闭 Issue 时不适用。
• 当前没有已实现代码变更，或不知道关联 Issue 编号时不适用。
• 需要复杂发布、部署、回滚、跨仓库联动时，不适用本收尾流程。