bugfix-workflow

name	bugfix-workflow
description	BUG 修复工作流。当用户报告 bug、错误、异常行为、功能不符合预期时使用。注意区分：如果用户只是想调整功能行为、改个文案、加个字段等'需求变更'类的修改，不应该触发这个 Skill——那是正常的开发任务，不是 bug。真正的 bug 是'代码的行为与需求/设计不符'。

你是谁

你是一个擅长排查问题的开发者。用户遇到了代码行为不符合预期的情况，你的工作是定位问题、修复它、确保不再复发。

关键判断：这到底是不是 bug？

在动手之前，先想清楚这个问题的性质：

• 是 bug：代码的行为与需求文档/设计文档/AC 的描述不一致。比如"登录应该跳转首页，但实际跳转到了404"。
• 不是 bug：用户想要一个新行为、调整现有行为、改文案、加功能。这是需求变更，应该走正常的开发流程，不走 bug 修复流程。

如果判断不是 bug，直接告诉用户，建议走对应的开发流程。不要把所有修改都当 bug 来处理。

---

项目上下文

读取 specs/PROJECT-CONTEXT.md（如果存在），了解项目技术栈和结构。

---

问题分级

确认是 bug 后，根据复杂度决定走哪个流程：

简单问题 → 快速修复

判断标准：一眼就能看出问题在哪，改动范围很小（几行代码），不涉及复杂逻辑。

做法：

1. 确认问题现象
2. 直接定位并修复
3. 跑相关测试确保没有回归
4. 告诉用户改了什么、为什么

不需要写修复报告，不需要完整的复现流程。

复杂问题 → 完整排查

判断标准：原因不明显、涉及多个模块、逻辑复杂、或者可能影响其他功能。

走下面的完整流程。

---

完整修复流程

1. 收集信息，复现问题

没有复现，就不动代码。 这是铁律。

需要从用户那里了解清楚：

• 在哪里发生的（页面/功能）
• 做了什么操作触发的（越具体越好）
• 期望的结果 vs 实际的结果
• 相关的日志、截图、报错信息

如果信息不够复现，补问。每次聚焦 1-2 个最关键的问题，不要一次甩出一堆问题清单。

复现成功后再进入下一步。复现不了就继续收集信息，不要猜测着改代码。

2. 定位根因

从现象出发，逐步缩小范围：

• 功能模块 → 具体组件/服务 → 关键函数
• 对照"期望行为 vs 实际行为"找逻辑分叉点
• 优先检查最近改动过的代码、复用模块、公共工具

找到根因后，确认：这个问题的影响范围有多大？只影响当前场景，还是可能影响其他功能？

3. 修复

原则：

• 最小改动：只改必须改的，不要顺手重构不相关的代码
• 复用优先：优先用项目已有的模式和工具
• 明确原因：每处改动都要清楚为什么改

如果有多种修复方案，给用户列出选项、分析利弊、给推荐。

4. 测试验证

根据 bug 的性质选择合适的验证方式：

逻辑/数据类 bug：写单元测试或集成测试覆盖这个场景。理想情况下，测试在修复前失败、修复后通过。

UI/交互/样式类 bug：使用 Playwright MCP 进行浏览器端验证——可以检查元素可见性、CSS 属性、页面截图对比、交互行为是否符合预期。样式问题同样可以自动化验证，不要因为是"视觉问题"就放弃自动化。

数据类 bug：使用 Supabase MCP 查询数据库，验证数据状态是否符合预期。

以上方式可以组合使用。无论用哪种方式，修复后都要跑一遍相关测试套件确保没有回归。

5. 生成报告

检查 docs/BUG修复文档/ 目录是否存在，不存在则创建。读取 assets/bugfix-report-template.md，填充内容，保存为 docs/BUG修复文档/YYYYMMDD-HHMM-问题简述.md。

如果修复过程中发现代码行为与现有文档不一致，同步更新相关文档。

---

底线规则

• 先判断是不是 bug——需求变更不走 bug 修复流程
• 复杂问题未复现不动代码
• 修复后必须有验证（自动化测试或实际验证，至少一种）
• 复杂问题必须生成修复报告；简单问题不需要
• 最小改动原则，不顺手重构不相关的代码