---
name: fix-issue
description: 处理 GitHub issue 的完整修复工作流。当用户提到 issue 编号、粘贴 GitHub issue URL、说"修一下这个 bug"、"处理一下这个 issue"、或需要根据 bug 报告修复代码时使用此 skill。即使用户只是提到了一个 GitHub 问题的链接或编号，也应该触发此 skill。
---

# fix-issue: GitHub Issue 修复工作流

你是一个专门处理 GitHub issue 的修复助手。收到 issue 后，你将自主完成从分析到提交的全流程。

## 输入格式

支持两种输入方式：

1. **URL 方式**：用户提供 GitHub issue URL（如 `https://github.com/owner/repo/issues/123`）
2. **描述方式**：用户直接描述问题（如 "登录页面点击提交按钮后崩溃" 或 "issue #456 的分页有问题"）

如果是 URL 方式，用 `gh` 命令获取 issue 信息。如果是描述方式，直接基于描述工作。

## 工作流程

### 阶段一：信息收集

**URL 方式：**

```bash
# 获取 issue 内容和元信息
gh issue view <number> --repo <owner/repo> --json title,body,labels,assignees,comments,state
```

提取以下信息：
- 问题标题和描述
- Labels（bug、enhancement、documentation 等）
- 评论中的补充信息（复现步骤、环境、错误日志、截图描述）
- 是否有关联的 PR 或重复 issue

**描述方式：**

基于用户提供的描述理解问题。如果信息不足，用 AskUserQuestion 补充询问（只问一次，不要反复追问）。

### 阶段二：问题分析与复杂度评估

分析收集到的信息，评估问题：

1. **问题本质**：这是一个什么类型的问题？（bug / 文档 / 性能 / 安全 / 重构）
2. **影响范围**：大概涉及哪些模块或文件？
3. **复杂度**：简单（单文件修复） / 中等（多文件但逻辑清晰） / 复杂（多模块耦合、需求不明确、或无法定位根因）

**复杂度判断规则：**

如果满足以下任一条件，判定为"复杂"，**必须停下来向用户汇报**，等用户决定下一步：
- 无法确定问题的根因（多个可能的嫌疑点）
- 修复可能影响 3 个以上模块
- issue 描述模糊，存在多种理解方式
- 需要添加新功能而非修复现有缺陷
- 涉及数据库迁移、API 契约变更等破坏性修改

汇报时说明：问题分析结果、可能的修复方向、以及为什么需要用户决策。

### 阶段三：工作区检查

开始修复前检查工作区状态：

```bash
git status
git stash list
```

- 如果工作区有未提交的更改，提醒用户先处理（stash 或提交），**不要自动 stash 或丢弃更改**
- 如果工作区干净，直接进入下一步
- 在当前分支上直接修复，不创建新分支

### 阶段四：代码定位与修复

1. 使用 Explorer subagent（`subagent_type: "Explore"`）探索代码库，定位问题相关代码。给 Explorer 足够的上下文——把 issue 的关键信息告诉它
2. 阅读相关代码，理解当前实现
3. 制定修复方案并实施代码修改

修复时遵循项目现有的代码风格和约定。参考 CLAUDE.md 中的项目规范。

### 阶段五：验证

修复完成后自动运行测试：

```bash
bun test
```

**测试失败处理：**
- 分析失败原因，判断是否由本次修复引起
- 如果是本次修复引起的，重新分析问题并修复，然后重跑测试
- 最多重试 **2 次**（总共最多 3 次测试运行：初次 + 2 次重试）
- 如果 2 次重试后仍然失败，停下来汇报失败原因和已尝试的方案，交给用户处理

### 阶段六：提交

测试通过后提交修复。

**提交策略：**
- 涉及多文件修改时，按逻辑分组提交（例如："修复数据层校验逻辑" 和 "修复 UI 层错误提示" 分开提交）
- 单文件或逻辑简单的修复直接一次提交

**Commit message 格式：**

```
fix: 简短描述 (#issue编号)
```

示例：
- `fix: 修复登录页提交按钮点击后崩溃的问题 (#123)`
- `fix: 修正分页组件页码计算逻辑 (#456)`
- `fix: 更新 API 文档中的错误返回值描述 (#789)`

对于非 bug 类型，对应调整 type：
- 文档问题：`docs: 修正 xxx 描述 (#issue)`
- 性能问题：`perf: 优化 xxx 性能 (#issue)`
- 重构：`refactor: 重构 xxx (#issue)`

提交后不自动创建 PR，也不输出完成提示。静默完成。

## 错误处理

- **`gh` 命令失败**：可能是 issue 不存在或权限不足。把错误信息展示给用户，让他们检查
- **找不到相关代码**：扩大搜索范围，如果仍然找不到，停下来告诉用户，附上已搜索的范围
- **测试超时**：如果是测试本身的问题（非修复引起），告知用户并跳过测试环节
- **合并冲突**：不会发生（在当前分支直接修复），但如果 `git status` 显示冲突，停下来让用户处理

## 全流程示例

用户说：`帮我修一下 https://github.com/owner/repo/issues/42`

1. 运行 `gh issue view 42 --repo owner/repo --json ...`，获取 issue 信息
2. 分析：issue 标题是"用户注册时邮箱校验失败"，评论中有复现步骤和错误日志。复杂度评估：简单（单文件修复）
3. `git status` 检查工作区干净
4. 用 Explore agent 搜索 "email" "validate" "register" 相关代码
5. 阅读 `src/services/auth/register.ts`，发现邮箱正则表达式不完整
6. 修复正则表达式
7. `bun test` → 通过
8. `git commit -m "fix: 修复用户注册时邮箱校验正则表达式不完整的问题 (#42)"`
9. 静默完成
