---
name: vaycentsun/sw-finishing-branch
source: https://app.decimal.ai/s/vaycentsun-sw-finishing-branch@1/SKILL.md
source_sha256: 532f4089c190
---

# Finishing Branch - 完成开发分支

所有任务完成后，验证、决策并清理开发分支。

## 核心原则

**完成 = 验证 + 决策 + 清理**

- 验证所有测试通过
- 呈现选项（合并/PR/保留/丢弃）
- 清理工作区

## 何时使用

```mermaid
flowchart TD
    A{所有任务完成？} -->|是| B{所有测试通过？}
    A -->|否| C[继续任务]
    B -->|是| D[sw-finishing-branch]
    B -->|否| E[修复测试]
    E --> B
```

## 完成流程

```mermaid
flowchart TD
    Start([开始]) --> VerifyTests[1. 验证所有测试<br/>运行完整测试套件]
    VerifyTests --> TestsOk{测试通过？}
    TestsOk -->|否| FixTests[修复失败的测试]
    FixTests --> VerifyTests
    TestsOk -->|是| FinalReview[2. 最终代码审查<br/>可选子 Agent]
    FinalReview --> PresentOptions[3. 呈现完成选项]
    PresentOptions --> UserChoice{用户选择}
    UserChoice -->|合并| Merge[4a. 合并到 main]
    UserChoice -->|PR| CreatePR[4b. 创建 PR]
    UserChoice -->|保留| Keep[4c. 保留分支]
    UserChoice -->|丢弃| Discard[4d. 丢弃分支]
    Merge --> Cleanup[5. 清理工作区]
    CreatePR --> Cleanup
    Keep --> Cleanup
    Discard --> Cleanup
    Cleanup --> UpdateSpec[6. 更新 Spec 状态]
    UpdateSpec --> Done([完成])
```

## 详细步骤

### 1. 确认整体测试状态

> **注意：** 任务级代码审查和功能验证已在每个任务完成后通过 `sw-code-review` 和 `sw-task-verification` 完成。本步骤仅确认所有任务合并后没有引入跨任务回归。

**运行完整测试套件**：

```bash
# Python
python -m pytest -v

# JavaScript
npm test

# 所有项目
make test  # 如果有
```

**确认要求**：
- [ ] 所有测试通过（回归检查）
- [ ] 无错误输出
- [ ] 无警告（或警告已记录并合理解释）

**如果测试失败**：
- 调用 `sw-systematic-debugging` 排查根因
- 修复后重新运行测试套件
- 重复直到全部通过

### 2. 跨任务一致性检查

> **注意：** 代码质量审查已在每个任务后通过 `sw-code-review` 完成。本步骤仅检查跨任务的一致性和完整性。

**检查清单**：
- [ ] 所有需求已实现（对照原始 Spec）
- [ ] 跨任务接口一致
- [ ] 文档已更新
- [ ] 无 TODO/FIXME 遗留
- [ ] 无调试代码

### 3. 呈现完成选项

向用户展示选项：

> ## 开发分支完成
> 
> **分支**: `feature/user-auth`
> **提交**: `abc1234`
> **测试状态**: ✅ 全部通过 (42/42)
> 
> ### 变更摘要
> - 新增文件: 8
> - 修改文件: 3
> - 删除文件: 0
> - 代码行数: +450/-120
> 
> ### 完成选项
> 
> **A) 合并到 main** [推荐]
> - 直接合并分支到 main
> - 删除开发分支
> - 清理工作区
> 
> **B) 创建 Pull Request**
> - 推送分支到远程
> - 创建 PR 供审查
> - 保留工作区等待合并
> 
> **C) 保留分支**
> - 保留分支和开发环境
> - 用于后续迭代
> 
> **D) 丢弃分支**
> - 删除分支和工作区
> - 保留代码变更（如有需要）
> 
> 请选择 (A/B/C/D)：

### 4. 执行用户选择

#### 选项 A: 合并到 main

```bash
# 切换到 main
git checkout main

# 合并分支
git merge feature/user-auth --no-ff -m "feat: user authentication

- Add User model with password hashing
- Implement login/logout functionality
- Add session management
- Add comprehensive tests

Closes #123"

# 推送
git push origin main

# 删除本地分支
git branch -d feature/user-auth

# 删除远程分支（如有）
git push origin --delete feature/user-auth
```

#### 选项 B: 创建 Pull Request

```bash
# 推送分支到远程
git push -u origin feature/user-auth

# 生成 PR 描述
```

**PR 描述模板**：
```markdown
## 描述
实现用户认证功能

## 变更
- 添加 User 模型
- 实现登录/登出
- 添加会话管理
- 添加测试

## 测试
- [x] 所有测试通过
- [x] 新增测试覆盖新功能

## Spec
关联: `docs/sw-agiledevelopment/technical-specs/2026-04-08--user-auth.md`

## 审查清单
- [x] 代码遵循项目规范
- [x] 测试覆盖充分
- [x] 文档已更新
```

#### 选项 C: 保留分支

```bash
# 推送分支到远程（确保备份）
git push -u origin feature/user-auth

# 保留本地分支和工作区
```

告知用户：
> 分支已保留。当前在 `feature/user-auth` 分支。
> 如需继续开发，可直接在此分支工作。

#### 选项 D: 丢弃分支

```bash
# 切换到 main
git checkout main

# 删除本地分支
git branch -D feature/user-auth

# 删除远程分支（如有）
git push origin --delete feature/user-auth
```

**注意**：如果用户想要保留代码但丢弃分支，先创建补丁：
```bash
git diff main..feature/user-auth > feature.patch
git checkout main
git branch -D feature/user-auth
```

### 5. 清理工作区

**清理检查清单**：
- [ ] 无孤立进程
- [ ] 磁盘空间已释放

### 6. 更新 Spec 状态

**更新 Spec 文件**：

```yaml
# 在 docs/sw-agiledevelopment/technical-specs/YYYY-MM-DD--feature.md 中

status: implemented  # 或 merged

implementation:
  # ... 原有内容
  
completion:
  completed_at: 2026-04-08
  completed_by: coder
  merge_commit: abc1234
  branch: feature/user-auth
  action: merged  # merged | pr | kept | discarded
```

**归档 Spec**：
```bash
# 如果项目有归档流程
git mv docs/sw-agiledevelopment/technical-specs/active/YYYY-MM-DD--feature.md docs/sw-agiledevelopment/technical-specs/archived/
git commit -m "docs: archive completed spec"
```

## 验证清单

完成前确认：

- [ ] 所有测试通过
- [ ] 无错误输出
- [ ] 用户已选择完成选项
- [ ] 选择已执行（合并/PR/保留/丢弃）
- [ ] 工作区已清理
- [ ] Spec 状态已更新
- [ ] 更改已提交/推送

## 输出示例

### 合并完成

```markdown
## 开发分支完成 - 已合并

**分支**: `feature/user-auth`
**操作**: 合并到 main
**合并提交**: `abc1234`
**时间**: 2026-04-08 14:30

### 变更统计
- 新增: 8 文件
- 修改: 3 文件
- 删除: 0 文件
- +450/-120 行

### 后续步骤
1. ✅ 分支已删除
2. ✅ Worktree 已清理
3. ✅ Spec 已归档
4. 🔄 CI/CD 正在运行 (https://ci.example.com/build/123)

### 相关资源
- Spec: `docs/sw-agiledevelopment/technical-specs/archived/2026-04-08--user-auth.md`
- 提交: `abc1234`
```

### PR 创建完成

```markdown
## 开发分支完成 - PR 已创建

**分支**: `feature/user-auth`
**操作**: 创建 Pull Request
**PR**: #45 (https://github.com/username/repo/pull/45)

### PR 状态
- 状态: 🟡 等待审查
- 审查者: (待分配)
- CI: 🟢 通过

### 后续步骤
1. 分配审查者
2. 等待审查反馈
3. 根据反馈修改
4. 合并到 main

### 保留资源
- Spec: `docs/sw-agiledevelopment/technical-specs/active/2026-04-08--user-auth.md`
```

## 集成

**前置 Skill**: 
- sw-subagent-development（完成所有任务）
- sw-task-verification（每个任务已通过验证）

**后续**: 无（工作流终点）

**相关 Skill**: 
- sw-code-review（如需最终代码审查）

## 红旗 - 阻止完成

| 想法 | 现实 |
|------|------|
| "测试大部分通过了，可以完成" | 测试未通过 = 不应完成。所有测试必须通过 |
| "严重 bug 先记录，以后修复" | 严重 bug 未修复 = 不应完成。合并严重 bug = 污染 main |
| "用户大概想合并" | 用户未明确选择 = 不应完成。必须确认用户意图 |
| "文档可以以后更新" | 未完成文档更新 = 不应完成。文档是交付的一部分 |
| "工作区以后清理" | 未清理工作区 = 不应完成。清理是完成的组成部分 |

## 常见借口表

| 借口 | 现实 |
|------|------|
| "就剩一个测试失败，先完成" | 一个失败测试可能隐藏严重问题。所有测试必须通过 |
| "用户忙，我先合并" | 未经用户明确确认的合并可能违背用户意图 |
| "文档不重要，代码才重要" | 文档是维护和理解代码的基础。不完整的文档 = 不完整的功能 |
| "工作区不占多少空间" | 未清理的工作区积累会导致混乱和资源浪费 |
| "以后修 bug 比现在更快" | 已知 bug 合并到 main 后修复成本更高 |

## 最佳实践

1. **总是运行完整测试** - 不只是修改的测试
2. **明确用户意图** - 确认用户想要合并/PR/保留/丢弃
3. **备份重要工作** - 推送分支到远程再删除本地
4. **更新文档** - 完成时更新 Spec 和 README
5. **清理彻底** - 不遗留临时文件或孤立目录