用途
devdocs-bugfix 是一套测试先行的 Bug 修复工作流，用于引导用户完成从复现 Bug、编写失败测试、修复代码到提交的完整过程，确保每个修复都有回归测试保护和记录。
触发条件包括：用户报告 Bug 或问题；用户提到“修复”“bug”“issue”“崩溃”“报错”；用户提供 Issue 编号或链接；测试执行失败（UT/IT/E2E）。
核心理念是：先证明 Bug 存在（失败测试），再修复代码，最后证明 Bug 已修复（测试通过）。每个 Bug 都要记录，形成知识沉淀。
主要能力
- 评估 Bug 复杂度。简单 Bug（单文件/单函数、原因明确）由本 Skill 直接修复；复杂 Bug（多模块、需拆分步骤、原因不明）必须走 /devdocs-dev-tasks 拆分任务。
- 定位代码，支持关键词搜索、错误信息搜索、从失败测试用例定位以及用户直接提供文件路径。
- 编写失败测试，测试命名规范为 should [预期行为] when [触发条件]，并要求添加 @verifies AC-XXX 与 @verifies BUG-XXX 标注。
- 修复代码，遵循最小改动、不引入新功能、遵循现有风格的原则，并参考 /code-quality 约束。
- 运行测试，包括新增的 Bug 修复测试与全部测试，确保没有引入回归。
- 记录 Bug 到 docs/devdocs/05-bugfix-log.md，编号格式为 BUG-XXX，编号延续现有文档中的最大编号。
- 生成 fix() 提交信息，遵循 /commit-convention，提交信息包含 BUG-XXX 编号并关联 Issue。
使用方式
工作流程为：理解 Bug 并评估复杂度 → 定位代码 → 编写失败测试 → 修复代码 → 运行测试 → 记录 Bug → 询问用户是否提交并生成 fix() 提交信息。
Step 1 需收集 Bug 描述、复现步骤、预期行为、实际行为、发现来源、关联功能（F-XXX / AC-XXX）以及可选的 Issue 编号；信息不足时使用 AskUserQuestion 询问。复杂度评估中若命中多模块/文件、原因不明、可能影响其他功能、需要多个步骤中任一项，必须走 /devdocs-dev-tasks 拆分任务，仅当用户明确选择“继续简单流程”时才允许跳过。
Step 2 向用户确认定位结果。
Step 3 编写失败测试并运行确认测试失败；测试失败表示 Bug 已复现，测试通过则说明 Bug 未复现需重新确认。测试结构需包含 Arrange、Act、Assert。
Step 5 运行测试，可参考命令：
npm test -- --testNamePattern="Bug fix"
npm test
Step 6 使用模板追加记录到 docs/devdocs/05-bugfix-log.md，记录字段包括发现来源、关联功能、Issue、严重程度（P0/P1/P2）、修复日期、状态、问题描述、复现步骤、根因分析、解决方案、回归测试、经验教训（可选）。
Step 7 提交前检查新增测试通过、全部测试通过、Bug 已记录、代码符合规范，提交信息格式为 fix(<scope>): <简述问题>，并包含根因、修复、测试与 BUG-XXX、Fixes #issue-number。
编排规范方面，复杂 Bug 路径下调用子技能必须通过 Task tool 启动子 Agent，涉及 /devdocs-dev-tasks、/devdocs-dev-workflow、/devdocs-sync；简单 Bug 因流程短，直接在 bugfix 上下文内执行，不启动子 Agent。调度原则包括上下文隔离、摘要传递、异常回退、不自行排障。
本 Skill 作为子 Agent 运行时，返回结构化摘要，包含 skill、bug_id、complexity、status、related、test_added、commit_hash、output_file 等字段。
适用场景
- 用户报告 Bug、崩溃、报错，或提供 Issue 编号/链接。
- 单元测试、集成测试或端到端测试执行失败后触发修复流程。
- 需要为 Bug 修复建立回归测试保护的开发场景。
- 需要记录 Bug 根因、解决方案并同步追溯矩阵的团队协作场景。
限制
- 流程约束：必须先编写失败测试再修复代码；测试必须先失败，证明 Bug 存在；修复后测试必须通过；不得跳过测试直接提交。
- 记录约束：每个 Bug 必须记录到 05-bugfix-log.md，必须记录发现来源、根因分析、解决方案，并关联回归测试编号。
- 追溯同步约束：修复完成后必须执行 /devdocs-sync，新增的回归测试必须登记到 03-test-*.md 追溯矩阵，否则 Bug 修复将成为“旁路”，测试无法追溯。
- 测试约束：测试名称描述 Bug 场景，覆盖 Bug 的触发条件，必须添加 @verifies AC-XXX 与 @verifies BUG-XXX 标注，禁止弱断言。
- 提交约束：提交信息使用 fix(<scope>): 前缀，包含 BUG-XXX 编号，关联 Issue 编号（如有）。
- 特殊情况：Bug 无法复现时需确认复现步骤、检查最近提交、与报告者确认环境信息；Bug 暴露设计缺陷时先用最小改动修复，记录设计缺陷到“经验教训”，可创建改进建议并使用 /refactor 进行系统性改进。
- 官方未提供的收费、价格、平台等信息暂未提供。