Finishing A Development Branch

完成开发分支

概览

通过提供清晰选项并处理所选工作流来指导开发工作的完成。

核心原则： 验证测试 → 检测环境 → 提供选项 → 执行选择 → 清理。

开始时声明： "I'm using the finishing-a-development-branch skill to complete this work."

流程

Step 1: 验证测试

提供选项前，验证测试通过：

# 运行项目的测试套件
npm test / cargo test / pytest / go test ./...

如果测试失败：

测试失败（<N> 个失败）。完成前必须修复：

[显示失败]

测试通过前，不能继续 merge/PR。

停止。不要继续 Step 2。

如果测试通过： 继续 Step 2。

Step 2: 检测环境

提供选项前，确定 workspace 状态：

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)

这会决定显示哪个菜单，以及清理如何工作：

Step 3: 确定基础分支

# 尝试常见基础分支
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

或者询问："This branch split from main - is that correct?"

Step 4: 提供选项

普通 repo 和具名分支 worktree——准确提供以下 4 个选项：

实现完成。你想怎么处理？

1. 在本地 merge 回 <base-branch>
2. Push 并创建 Pull Request
3. 保持分支原样（我稍后处理）
4. 丢弃这项工作

选择哪一项？

Detached HEAD——准确提供以下 3 个选项：

实现完成。你位于 detached HEAD（外部管理的 workspace）。

1. 作为新分支 push 并创建 Pull Request
2. 保持原样（我稍后处理）
3. 丢弃这项工作

选择哪一项？

不要添加解释 - 保持选项简洁。

Step 5: 执行选择

Option 1: 本地 Merge

# 获取 main repo root，保证 CWD 安全
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# 先 merge——删除任何东西前验证成功
git checkout <base-branch>
git pull
git merge <feature-branch>

# 验证 merge 后结果上的测试
<test command>

# 仅在 merge 成功后：清理 worktree（Step 6），然后删除分支

然后：清理 worktree（Step 6），再删除分支：

git branch -d <feature-branch>

Option 2: Push 并创建 PR

# Push 分支
git push -u origin <feature-branch>

# 创建 PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## 总结
<2-3 条更改内容>

## 测试计划
- [ ] <验证步骤>
EOF
)"

不要清理 worktree——用户需要它保留，以便根据 PR 反馈迭代。

Option 3: 保持原样

报告："Keeping branch . Worktree preserved at ."

不要清理 worktree。

Option 4: 丢弃

先确认：

这将永久删除：
- Branch <name>
- 所有 commits：<commit-list>
- 位于 <path> 的 worktree

输入 'discard' 确认。

等待完全一致的确认。

如果已确认：

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

然后：清理 worktree（Step 6），再强制删除分支：

git branch -D <feature-branch>

Step 6: 清理 Workspace

仅针对 Options 1 和 4 运行。 Options 2 和 3 始终保留 worktree。

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

如果 GIT_DIR == GIT_COMMON： 普通 repo，没有要清理的 worktree。完成。

如果 worktree 路径位于 .worktrees/、worktrees/ 或 ~/.config/superpowers/worktrees/ 下： Superpowers 创建了这个 worktree——我们负责清理。

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune  # 自愈：清理任何陈旧注册

否则： 宿主环境（harness）拥有这个 workspace。不要移除它。如果你的平台提供 workspace-exit 工具，就使用它。否则，将 workspace 保留在原位。

快速参考

常见错误

跳过测试验证

• 问题： Merge 损坏的代码，创建失败的 PR
• 修复： 提供选项前始终验证测试

开放式问题

• 问题： "What should I do next?" 含糊不清
• 修复： 准确提供 4 个结构化选项（detached HEAD 则为 3 个）

为 Option 2 清理 worktree

• 问题： 移除了用户进行 PR 迭代所需的 worktree
• 修复： 仅为 Options 1 和 4 清理

移除 worktree 前删除分支

• 问题： git branch -d 失败，因为 worktree 仍引用该分支
• 修复： 先 merge，移除 worktree，再删除分支

在 worktree 内部运行 git worktree remove

• 问题： 当 CWD 位于要移除的 worktree 内时，命令会静默失败
• 修复： 在 git worktree remove 前始终 cd 到 main repo root

清理 harness 拥有的 worktree

• 问题： 移除 harness 创建的 worktree 会导致幽灵状态
• 修复： 只清理 .worktrees/、worktrees/ 或 ~/.config/superpowers/worktrees/ 下的 worktree

丢弃时没有确认

• 问题： 意外删除工作
• 修复： 要求输入 "discard" 确认

危险信号

绝不要：

• 在测试失败时继续
• 未在结果上验证测试就 merge
• 未确认就删除工作
• 未明确请求就 force-push
• 确认 merge 成功前移除 worktree
• 清理不是你创建的 worktree（来源检查）
• 从 worktree 内部运行 git worktree remove

始终：

• 提供选项前验证测试
• 展示菜单前检测环境
• 准确提供 4 个选项（detached HEAD 则为 3 个）
• 为 Option 4 获取输入确认
• 仅为 Options 1 和 4 清理 worktree
• 移除 worktree 前 cd 到 main repo root
• 移除后运行 git worktree prune