fix

修复

范围门槛（开始前必须确认）

仅当以下所有条件都满足时，才使用此技能：

1. 存在明确的问题信号

   • 已发现清晰的异常行为、错误或回归
   • 证据充分，可以开始诊断（日志、堆栈跟踪、失败的测试或可复现的步骤）

2. 可能采用局部修复路径

   • 问题似乎局限在较小范围内
   • 预计不需要跨系统重新设计或迁移

3. 架构风险低至中等

   • 无需基础性改动即可修复
   • 预计不需要分阶段推出或功能标志策略

4. 验证路径直接明了

   • 可在实际可行的范围内复现问题并进行修复后检查
   • 可直接验证成功标准

如果任何条件不满足，请升级到 brainstorm 或 write-plan。

必须停止并升级的条件

出现以下任一情况时，立即停止并转入规划：

• 经过有针对性的调查后，根本原因仍不明确
• 修复需要跨领域的架构或数据模型变更
• 范围扩大到大规模重构或多模块迁移
• 涉及安全或合规敏感行为
• 验证发现大范围回归，需要分阶段缓解
• 多次尝试修复均未能找到明确的根本原因

升级操作：

1. 停止所有实施活动。
2. 输出以下确切消息："This fix exceeds safe single-pass debugging limits. Ask, Recommend brainstorm or write-plan first to define phased diagnosis, implementation, and risk controls."

工作流

步骤 1：接收问题并梳理上下文

1. 了解报告的 Bug，并明确预期行为。
2. 收集／确认 Bug 报告所需的最低信息：
   • 标题
   • 预期行为
   • 实际行为
   • 复现步骤
   • 证据（日志、跟踪信息、截图、失败的测试输出）
   • 环境（相关时注明分支／OS／运行时／版本）
   • 影响／严重程度
3. 仅加载与 Bug 相关的项目上下文：
   • 如果存在 docs/SUMMARY.md，先阅读。
   • 仅加载与任务相关的详细文档。
   • 优先遵循 Code Standard 文档中的实现规范。
   • 如果文档与代码或用户意图冲突，在进行大范围更改前使用可用的输入／提问工具。

步骤 2：复现并诊断

1. 稳定复现问题。
2. 找出故障点（文件／函数／行范围／子系统）。
3. 跟踪控制流和数据流，找出根本原因。
4. 提出修复假设，并确认其能够解释观察到的行为。

指南：

• 阅读周边代码，不要只看发生故障的行。
• 优先修正根本原因，而不是修补表面症状。
• 仅在必要时添加临时诊断信息；使用后将其移除。

步骤 3：判断修复规模与风险

编码前先对工作进行分类：

小型修复（继续使用此技能）

大多数条件成立：

• 根本原因明确且已验证
• 变更范围较窄（通常只涉及少数几个文件）
• 回归风险有限，且可快速测试

较大或高风险的修复（升级到 brainstorm 或 write-plan）

任一条件成立：

• 根本原因尚不确定
• 必须同时更改多个子系统
• 需要迁移、安排推出顺序或进行大范围重构
• 无法在单次处理中合理控制风险

如果修复规模较大，请遵循必须停止并升级的条件。

步骤 4：实施（小型修复路径）

1. 列出简短的 1–3 条实施计划。
2. 以最小且有针对性的更改解决根本原因。
3. 严格控制范围；避免无关重构。
4. 适用时添加／更新回归测试。

步骤 5：验证

按范围由小到大运行验证：

1. 针对变更行为／模块的检查
2. 附近功能的回归检查
3. 视需要运行相关项目检查（lint／类型检查／测试／构建）

只有满足以下条件，修复才算完成：

• 问题不再能够复现
• 已确认预期行为
• 未引入严重回归

如果验证表明影响范围更广，请升级到 brainstorm 或 write-plan。

第 6 步：完成并报告

提供简洁的完成报告，包含：

• 根本原因
• 变更内容
• 此修复为何有效
• 已执行的验证及结果
• 剩余风险／后续事项

如果行为或文档相关规则发生变化，请更新最少量的相关文档。如果架构发生变化，应已上报。

规则

• 缺少关键信息时，不要猜测。
• 始终优先修复根本原因。
• 将影响范围控制在最小。
• 未经验证，不要标记为已完成。
• 如果范围／风险超出此技能的能力，应尽早上报。

可选的 Bug 报告模板

报告信息不完整时使用：

• 标题：
• 预期行为：
• 实际行为：
• 复现步骤：
• 错误日志／堆栈跟踪：
• 环境：
• 影响／严重程度：
• 其他背景信息：