fix-hard

[IMPORTANT] 开始前，使用 TaskCreate 将所有工作拆分为小任务——包括为每个文件的读取创建任务。这样可以避免因文件过长而丢失上下文。对于简单任务，AI MUST ATTENTION 询问用户是否跳过。

先理解代码 — 严格门槛：在阅读现有代码之前，不要编写、规划或修复任何内容。

1. 搜索 3 个或更多相似模式（grep/glob）——引用 file:line 作为依据
2. 阅读目标区域中的现有文件——了解其结构、基类和约定
3. 当 .code-graph/graph.db 存在时，运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——弄清哪些内容依赖目标对象
5. 对于非简单任务（涉及 3 个或更多文件），将调查结果写入 .ai/workspace/analysis/
6. 实施前重新阅读分析文件——切勿仅凭记忆开展工作
7. 如果现有模式可用，绝不另创模式——严格遵循现有模式，或记录偏离原因

满足以下条件前禁止继续： - [ ] 已阅读目标文件 - [ ] 已检索 3 个或更多模式 - [ ] 已进行图追踪（如果 graph.db 存在） - [ ] 已通过证据验证假设

基于证据进行推理 — 禁止猜测。每项断言都必须有依据。

1. 每项断言都要引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接行动，60-80% 先验证，<60% 不要提出建议
3. 架构变更必须进行跨服务验证
4. “我没有足够的证据”是有效且符合预期的输出

满足以下条件前禁止继续： - [ ] 证据文件路径（file:line） - [ ] 已执行 grep 搜索 - [ ] 已找到 3 个或更多相似模式 - [ ] 已声明置信度

无证据时禁止使用：“显然”“我认为”“应该是”“可能是”“这是因为” 如果信息不完整 → 输出："Insufficient evidence. Verified: [...]. Not verified: [...]."

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系和跨服务同步（任务涉及业务实体/模型时阅读）（内容会由 hook 自动注入——阅读前检查是否有 [Injected: ...] 标头）

估算 — 修改后的斐波那契数列：1（简单）→ 2（较小）→ 3（中等）→ 5（较大）→ 8（非常大）→ 13（史诗级，应拆分）→ 21（必须拆分）。在计划 frontmatter 中输出 story_points 和 complexity。复杂度自动推导：1-2=低，3-5=中，8=高，13+=严重。 按层负责修复 — 绝不要在崩溃现场修复。追踪完整流程，在负责该问题的层修复。

AI 的默认行为：在 A 处看到错误 → 在 A 处修复。这是错误的。崩溃现场是症状，不是原因。

任何修复前都必须：

1. 追踪完整数据流 — 跨所有层映射从数据来源到崩溃现场的完整路径（存储 → 后端 → API → 前端 → UI）。找出错误状态从何处进入，而不是它在哪里崩溃。
2. 确定不变量的负责层 — 哪一层的契约保证此值有效？该层就应负责。在拥有该不变量的最低层修复，而不是在使用它的最高层修复。
3. 一次修复，最大限度保护 — 问自己：“如果在这里修复，能否只改一次就保护所有下游使用方？”如果修复需要修改 3 个以上文件并添加防御性检查，那说明你选错了层——应该再往下找。
4. 确认没有绕过路径 — 确认所有数据流都会经过修复点。检查是否存在：跳过工厂的直接构造、未经重新验证的克隆／展开、未封装在领域模型中的原始数据、模型层之外的变更。

以下事项完成前禁止修复： - [ ] 已追踪完整数据流（来源 → 崩溃） - [ ] 已通过 file:line 证据确定不变量的负责层 - [ ] 已审查所有访问点（grep 计数） - [ ] 已说明修复层的依据（能保护最多使用方的最低层）

反模式（拒绝这些做法）：

• “在崩溃处修复” — 崩溃现场 ≠ 原因现场。应向上游追踪。
• “在每个使用方添加防御性检查” — 分散防御 = 选错层。一个权威修复 > 多个分散的保护性检查。
• “两处都修复更安全” — 选定一个权威层。跨层重复检查会混淆不变量的负责方。

技能变体： /fix 的变体 — 面向复杂问题，借助子 Agent 深入调查。

快速摘要

目标： 使用并行子 Agent 调查，系统地诊断并修复复杂 Bug。

工作流：

1. 侦察 — 使用侦察／研究子 Agent 并行探索问题
2. 诊断 — 通过代码路径和证据追踪根因
3. 规划 — 制定包含影响分析的修复计划
4. 修复 — 实施并验证修复

关键规则：

• 调试思维：每项断言都需要 file:line 证据
• 使用子 Agent 并行调查多个假设
• 实施复杂修复前，务必先制定计划

根因调试 — 采用系统化方法，绝不靠猜测和反复试错。

1. 复现 — 通过证据确认问题存在（错误消息、堆栈跟踪、截图）
2. 隔离 — 使用二分查找和图追踪，将范围缩小到具体文件／函数／行
3. 追踪 — 跟踪从输入到故障点的数据流。阅读实际代码，不要推断。
4. 提出假设 — 给出带置信度百分比的理论。说明哪些证据支持或反驳它
5. 验证 — 使用有针对性的 grep／阅读来检验假设。一次只改变一个变量。
6. 修复 — 解决根因，而非症状。通过图的 connections 验证修复不会破坏调用方

绝不： 在没有证据时猜测。修复症状而非原因。跳过复现步骤。

调试思维（不可妥协）

保持审慎。运用批判性思维和顺序思维。每项断言都需要经过追踪的证明和置信度百分比（想法应超过 80%）。

• 不要假设第一个假设就是正确的——通过实际代码追踪进行验证
• 每项根因断言都必须包含 file:line 证据
• 如果无法通过代码追踪证明根因，请说明“假设，尚未确认”
• 质疑假设：“这真的是原因吗？”→ 追踪实际执行路径
• 质疑完整性：“是否还有其他促成因素？”→ 检查相关代码路径
• 没有证据时，不要说“应该能修好”——验证修复确实解决了追踪到的根因

⚠️ 强制要求：置信度与证据门槛

强制要求： 每项声明都必须附上 Confidence: X%、证据列表和 file:line 证明。 95% 以上：可自由推荐 | 80–94%：需附带注意事项 | 60–79%：列出未知信息 | 低于 60%：停止——收集更多证据。

深入思考，遵循编排协议、核心职责、子 Agent 团队和开发规则，规划并开始修复以下问题： $ARGUMENTS

工作流：

如果用户提供了截图或视频，请使用 ai-multimodal 技能尽可能详细地描述问题，确保开发人员能根据描述轻松推断根本原因。

完成请求

质疑一切：使用 AskUserQuestion 工具提出深入的问题，充分了解用户的请求、约束和真正目标。不要想当然——持续澄清，直到完全确定。

• 如果有任何疑问，请使用 AskUserQuestion 工具向用户澄清。
• 一次只问一个问题，等待用户回答后再问下一个。
• 如果没有疑问，请开始下一步。

⚠️ 修复前验证（不可妥协）： 找出根本原因并制定计划后，必须使用 AskUserQuestion 向用户展示调查结果和拟议的修复计划，并获得明确批准，然后才能更改任何代码。不得擅自修复。

修复问题

使用 sequential-thinking 技能，将复杂问题拆解为循序渐进的思考步骤。 使用 problem-solving 技能解决问题。 分析技能目录，并在过程中启用任务所需的其他技能。

1. 使用 debugger 子 Agent 查找问题的根本原因，并向主 Agent 汇报。 1.5. 将调查结果写入 .ai/workspace/analysis/{issue-name}.analysis.md。制定修复计划前，重新阅读整个文件。
2. 使用 researcher 子 Agent（如有需要）快速研究根本原因的相关网络资料，并向主 Agent 汇报。
3. 使用 planner 子 Agent 根据各方报告制定实施计划，然后向主 Agent 汇报。
4. 🛑 展示根本原因和修复计划 → 使用 AskUserQuestion → 等待用户批准。
5. 然后使用 /code SlashCommand，逐步实施计划。
6. 最终报告：

• 向用户汇报更改摘要并简要解释，指导用户开始使用并建议后续步骤。
• 询问用户是否要将更改提交并推送到 git 仓库；如果要，请使用 git-manager 子 Agent 提交并推送到 git 仓库。

• 重要： 撰写报告时，可牺牲语法完整性以求简洁。
• 重要： 如有未解决的问题，请在报告末尾列出。

请记住：

• 你可以随时使用 ai-multimodal 技能生成图像素材。

• 你必须使用 ai-multimodal 技能读取并分析生成的素材，以验证其符合要求。

• 对于图像编辑（去除背景、调整、裁剪），请按需使用 media-processing 技能。

• 修复后，必须运行 /prove-fix——为每项更改构建代码证明轨迹并给出置信度评分。不得跳过。

---

后续步骤（独立模式：必须使用 AskUserQuestion 询问用户。若处于工作流中，则跳过。）

强制要求：无一例外： 如果在工作流之外调用此技能，必须使用 AskUserQuestion 向用户展示以下选项。即使任务看起来「简单」或「显而易见」，也不得跳过——由用户决定：

• 「继续完整工作流（推荐）」——我将从此处（修复已应用）判断并继续最合适的工作流，确保不会漏掉 prove-fix、审查、测试和文档步骤。
• 「/prove-fix」——通过代码轨迹证明修复正确。
• 「/test」——运行测试以验证修复。
• 「跳过，手动继续」——由用户决定

如果已处于工作流中，则跳过——工作流会负责安排后续步骤。

收尾提醒

• 重要：务必注意 在开始之前，使用 TaskCreate 将工作拆分为较小的待办任务

• 重要：务必注意 在编写新代码之前，搜索代码库中的 3 个或更多类似模式

• 重要：务必注意 为每项声明提供 file:line 证据（置信度 >80% 时再采取行动）

• 重要：务必注意 添加最终审核待办任务，以检查工作质量

• 重要：务必注意 失败修复 3 次后停止——报告结果，并在第 4 次尝试前询问用户 强制重要：务必注意 开始之前阅读以下文件：

• 重要：务必注意 在进行任何修改之前，搜索 3 个或更多现有模式并阅读代码。若存在 graph.db，则运行图追踪。

• 重要：务必注意 为每项声明提供 file:line 证据。置信度 >80% 时再采取行动，<60% 时不得提出建议。

• 重要：务必注意 在计划 frontmatter 中包含 story_points 和 complexity。SP > 8 时拆分。

• 重要：务必注意 追踪完整的数据流，并在负责该逻辑的层修复，而不是在崩溃位置修复。添加 ?. 之前，审查所有访问位置。