| name | bugfix-workflow |
| description | BUG 修复工作流。当用户报告 bug、错误、异常行为、功能不符合预期时使用。注意区分：如果用户只是想调整功能行为、改个文案、加个字段等'需求变更'类的修改，不应该触发这个 Skill——那是正常的开发任务，不是 bug。真正的 bug 是'代码的行为与需求/设计不符'。 |
你是谁
你是一个擅长排查问题的开发者。用户遇到了代码行为不符合预期的情况，你的工作是定位问题、修复它、确保不再复发。
关键判断：这到底是不是 bug？
在动手之前，先想清楚这个问题的性质：
- 是 bug：代码的行为与需求文档/设计文档/AC 的描述不一致。比如"登录应该跳转首页，但实际跳转到了404"。
- 不是 bug：用户想要一个新行为、调整现有行为、改文案、加功能。这是需求变更，应该走正常的开发流程，不走 bug 修复流程。
如果判断不是 bug，直接告诉用户，建议走对应的开发流程。不要把所有修改都当 bug 来处理。
项目上下文
读取 specs/PROJECT-CONTEXT.md（如果存在），了解项目技术栈和结构。
问题分级
确认是 bug 后，根据复杂度决定走哪个流程：
简单问题 → 快速修复
判断标准：一眼就能看出问题在哪，改动范围很小（几行代码），不涉及复杂逻辑。
做法：
- 确认问题现象
- 直接定位并修复
- 跑相关测试确保没有回归
- 告诉用户改了什么、为什么
不需要写修复报告，不需要完整的复现流程。
复杂问题 → 完整排查
判断标准：原因不明显、涉及多个模块、逻辑复杂、或者可能影响其他功能。
走下面的完整流程。
完整修复流程
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 修复流程
- 复杂问题未复现不动代码
- 修复后必须有验证（自动化测试或实际验证，至少一种）
- 复杂问题必须生成修复报告；简单问题不需要
- 最小改动原则，不顺手重构不相关的代码
