# Skill: Bug 修复文档

为 Bug 修复生成结构化文档，记录问题分析、根因、修复方案和验证结果，确保知识沉淀。

## 适用场景

- 复杂 Bug 修复（需要重构或影响多个模块）
- 需要记录根因分析的 Bug
- 需要团队知识共享的 Bug

## 不适用场景

- 简单 Bug（单文件、单方法修改）→ 直接修复即可
- 代码格式调整 → 运行 `make fmt` 即可
- 文档更新 → 直接修改文档即可

## 执行步骤

1. 读取 GitHub Issue 或 Bug 报告
2. 使用 Explore agent 定位相关代码
3. 分析问题根因
4. 设计修复方案（如需重构，参考 `/backend-design` 或 `/frontend-design`）
5. 生成 `bugfix.md`

## 输出文件

`console/.claude/docs/bugfix-{issue-number}/bugfix.md`

## 输出模板

```markdown
---
issue: #{issue-number}
title: {Issue 标题}
severity: {Critical/High/Medium/Low}
module: {所属模块}
created: {YYYY-MM-DD}
fixed: {YYYY-MM-DD}
---

# Bug #{issue-number}: {Issue 标题}

## 1. 问题描述

**现象**:
{用户报告的问题现象，1-2 句话}

**复现步骤**:
1. {步骤1}
2. {步骤2}
3. {步骤3}

**预期行为**:
{应该发生什么}

**实际行为**:
{实际发生了什么}

**影响范围**:
- 影响用户: {哪些用户受影响}
- 影响功能: {哪些功能受影响}
- 严重程度: {Critical/High/Medium/Low}

## 2. 问题定位

**相关代码文件**:
| 文件路径 | 行号 | 说明 |
|---------|------|------|
| `{file-path}` | {line} | {问题所在} |

**错误堆栈** (如适用):
```
{错误堆栈信息}
```

**关键代码片段**:
```java
// {file-path}:{line-number}
{有问题的代码}
```

## 3. 根因分析

**根本原因**:
{一段话说明问题的根本原因，不是表面现象}

**为什么会发生**:
- 原因1: {说明}
- 原因2: {说明}

**为什么之前没发现**:
- {测试覆盖不足 / 边界条件未考虑 / 代码逻辑缺陷 / ...}

**相关设计缺陷** (如适用):
- {指出设计层面的问题}

## 4. 修复方案

### 方案选择

**考虑的方案**:

| 方案 | 优点 | 缺点 | 是否采用 |
|------|------|------|----------|
| 方案A: {描述} | {优点} | {缺点} | ✅ 采用 |
| 方案B: {描述} | {优点} | {缺点} | ❌ 不采用 |

**最终方案**: 方案A

**选择理由**: {为什么选择这个方案}

### 修改内容

**修改文件清单**:
| 文件路径 | 修改类型 | 说明 |
|---------|---------|------|
| `{file-path}` | 修改 | {修改内容} |
| `{file-path}` | 新增 | {新增内容} |

**核心修改**:

#### 修改点 1: {描述}

**文件**: `{file-path}:{line-number}`

**修改前**:
```java
{原代码}
```

**修改后**:
```java
{新代码}
```

**修改原因**: {为什么这样改}

#### 修改点 2: {描述}

...（同上格式）

### 数据库变更 (如适用)

**Flyway 脚本**: `V{version}__{description}.sql`

```sql
-- {说明}
ALTER TABLE {table_name} ...;
```

## 5. 影响分析

**向后兼容性**:
- ✅ 完全兼容 / ⚠️ 需要数据迁移 / ❌ 破坏性变更

**影响范围**:
- 后端: {影响的 Service/Controller}
- 前端: {影响的页面/组件}
- 数据库: {影响的表/字段}
- API: {影响的接口}

**风险评估**:
- 风险等级: {低/中/高}
- 潜在风险: {列出可能的风险}
- 缓解措施: {如何降低风险}

## 6. 验证方案

### 单元测试

**新增测试**:
```java
@Test
public void test{Scenario}() {
    // Given
    // When
    // Then
}
```

### 功能测试

**测试场景**:

| 场景 | 输入 | 预期结果 | 实际结果 |
|------|------|----------|----------|
| {场景1} | {输入} | {预期} | ✅ 通过 |
| {场景2} | {输入} | {预期} | ✅ 通过 |

### 回归测试

**需要回归的功能**:
- [ ] {功能1}
- [ ] {功能2}

## 7. 预防措施

**如何避免类似问题**:
- [ ] 添加单元测试覆盖边界条件
- [ ] 添加参数校验
- [ ] 更新代码审查检查清单
- [ ] 更新文档说明
- [ ] 重构相关代码

**需要改进的地方**:
- {代码层面}: {改进建议}
- {测试层面}: {改进建议}
- {流程层面}: {改进建议}

## 8. 相关文档更新

**需要更新的文档**:
- [ ] `console/.claude/docs/{module}/module.md` - {更新内容}
- [ ] `console/backend/CLAUDE.md` - {更新内容}（如适用）
- [ ] `console/frontend/CLAUDE.md` - {更新内容}（如适用）

## 9. 参考资料

- Issue: https://github.com/iflytek/astron-agent/issues/{number}
- 相关 PR: #{pr-number}
- 相关文档: {链接}
```

## 约束

- 必须读取实际代码，不要猜测
- 根因分析必须深入到本质，不能停留在表面
- 修复方案必须考虑多个选项，说明选择理由
- 必须包含验证方案和预防措施
- 中文为主，代码和路径保留英文

## 使用示例

### 示例 1: Issue #941 - 非个人空间复制智能体报错

```bash
# 1. 调用 skill
/bugfix

# 2. Claude 会询问 Issue 编号
输入: 941

# 3. Claude 自动:
#    - 读取 Issue 内容
#    - 定位相关代码
#    - 分析根因
#    - 生成 bugfix.md

# 4. 输出文件
console/.claude/docs/bugfix-941/bugfix.md
```

### 示例 2: 快速修复（不生成文档）

对于简单 Bug，直接修复即可，不需要调用此 skill:

```bash
# 简单 Bug: 直接修复
1. 定位代码
2. 修改代码
3. 运行 make check && make test
4. 提交: git commit -m "fix(module): resolve issue #123"
```

## 何时使用此 Skill

**使用此 Skill**:
- ✅ Bug 需要修改 ≥3 个文件
- ✅ Bug 需要数据库迁移
- ✅ Bug 涉及复杂业务逻辑
- ✅ Bug 需要团队知识共享
- ✅ Bug 的根因需要深入分析

**不使用此 Skill**:
- ❌ 单文件、单方法修改
- ❌ 代码格式调整
- ❌ 简单的空指针修复
- ❌ 配置文件调整
