fix-parallel

[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. 如果现有模式可用，绝不另创模式——严格遵循，或说明偏离原因

解除阻塞前必须完成： - [ ] 已阅读目标文件 - [ ] 已 Grep 搜索 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 — 领域实体目录、关系、跨服务同步（任务涉及业务实体/模型时阅读）（内容由钩子自动注入——阅读前检查是否有 [Injected: ...] 标头）

估算 — 修改版斐波那契：1（琐碎）→ 2（小）→ 3（中）→ 5（大）→ 8（很大）→ 13（史诗级，应拆分）→ 21（必须拆分）。在计划 frontmatter 中输出 story_points 和 complexity。复杂度自动推导：1-2=低，3-5=中，8=高，13+=严重。

红旗停止条件 — 出现以下情况时，停止并通过 AskUserQuestion 向用户升级确认：

1. 任何关键决策的置信度低于 60%
2. 变更会影响超过 20 个文件（影响范围过大）
3. 跨越服务边界
4. 涉及安全敏感代码（身份验证、加密、PII 处理）
5. 检测到破坏性变更（接口、API 契约、数据库架构）
6. 变更后测试覆盖率会降低
7. 方案需要使用项目中没有的技术/模式

未经用户明确批准，绝不能越过红旗继续执行。

技能变体： /fix 的变体——使用子 Agent 并行解决多个问题。

快速摘要

目标： 使用并行的全栈开发子 Agent 同时修复多个相互独立的问题。

工作流：

1. 分类 — 对问题进行分类并确认彼此独立（没有共享文件）
2. 分配 — 将问题分配给并行子 Agent，并严格划分文件所有权
3. 执行 — 子 Agent 各自独立修复问题
4. 合并 — 审查并集成所有修复

关键规则：

• 调试思维：每项主张都需要 file:line 证据
• 问题必须相互独立，不得修改重叠的文件
• 每个子 Agent 负责指定文件；不得跨越文件边界修改

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

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

绝不： 在没有证据的情况下猜测；只修复症状而不解决根因；跳过复现步骤。

前端／UI 上下文（如适用）

如果此任务涉及前端或 UI 更改，

UI 系统上下文 — 对于涉及 .ts、.html、.scss 或 .css 文件的任何任务：

实施前必须阅读：

1. docs/project-reference/frontend-patterns-reference.md — 组件基类、存储、表单
2. docs/project-reference/scss-styling-guide.md — BEM 方法、SCSS 变量、混入、响应式设计
3. docs/project-reference/design-system/README.md — 设计令牌、组件清单、图标

参考 docs/project-config.json 获取项目特定路径。

• 组件模式：docs/project-reference/frontend-patterns-reference.md
• 样式／BEM 指南：docs/project-reference/scss-styling-guide.md
• 设计系统令牌：docs/project-reference/design-system/README.md

调试思维（不可妥协）

保持审慎。运用批判性思维和顺序思维。每项主张都必须有可追溯的证据和置信度百分比（想法的置信度应高于 80%）。

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

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

每项主张都必须声明 Confidence: X%，并附上证据清单和 file:line 证明。此要求为强制要求。 95% 及以上可直接推荐 | **80–94%**需注明保留条件 | **60–79%**列出未知项 | 低于 60%：停止——收集更多证据。

⚠️ 修复前验证（不可妥协）： 完成根因分析和计划制定后，必须通过 AskUserQuestion 向用户展示调查结果和拟议的修复计划，并在进行任何代码更改前获得明确批准。不得默默修复。

超前思考并行修复：$ARGUMENTS

重要： 激活所需技能。确保高效使用 token。为简洁可牺牲语法。

工作流

1. 问题分析

• 使用 debugger 子 Agent 分析根因
• 使用 /scout-ext 查找相关文件
• 按范围／领域对问题分类（前端、后端、身份验证、支付等）
• 确定问题之间的依赖关系
• 外部记忆：每个并行 Agent 将调查结果写入 .ai/workspace/analysis/{issue-name}-{agent}.analysis.md。主 Agent 在协调修复前重新阅读全部内容。

2. 并行规划修复

• 触发 /plan-parallel <detailed-fix-instructions>，生成可并行执行的修复计划
• 等待计划，计划中应包含依赖关系图、执行策略和文件所有权矩阵
• 将互不依赖的修复分组并行执行
• 有依赖关系的问题按顺序修复
• 🛑 展示根本原因和修复计划 → AskUserQuestion → 等待用户批准后再启动 Agent。

3. 并行实施修复

• 阅读 plan.md 中的依赖关系图
• 对互不依赖的修复，并行启动多个 fullstack-developer Agent
  • 示例：“修复身份验证 + 修复支付 + 修复 UI” → 同时启动 3 个 Agent
  • 传递阶段文件路径：{plan-dir}/phase-XX-*.md
  • 包含环境信息
• 等待所有并行修复完成后，再处理有依赖关系的修复
• 顺序修复：每次只启动一个 Agent

子 Agent 上下文规范：

• 提供完整任务文本 — 将任务内容粘贴到子 Agent 提示词中；不要让子 Agent 读取计划文件
• “开始前先提问” — 子 Agent 应先指出不确定之处，再开始实施
• 提交结果前先自我审查 — 子 Agent 应在返回结果前检查完整性、质量和 YAGNI

4. 测试

• 使用 tester 子 Agent 运行完整测试套件
• 不得使用伪造数据、模拟对象或作弊手段
• 验证所有问题均已解决
• 如果失败：使用 debugger，修复后重复测试

5. 代码审查

两阶段任务审查 — 标记任务完成前，必须完成两个阶段。

阶段 1：自我审查 — 实施完成后立即进行：

• 是否满足要求？是否引入回归？代码质量是否合格？

阶段 2：交叉审查 — 通过 code-reviewer 子 Agent 进行：

• 发现盲点、偏离规范和遗漏的边缘情况

绝不可跳过阶段 2。 仅靠自我审查会漏掉 40% 以上的问题。

1. 首先：派遣 `spec-compliance-reviewer`，验证每项修复是否符合其规范
2. 只有规范审查通过后：才派遣 `code-reviewer` 进行质量审查

• 验证修复不会引入回归
• 如果存在严重问题：修复并重新测试

6. 项目管理与文档

• 如果获批：并行使用 project-manager 和 docs-manager
• 更新计划文件、文档和路线图
• 如果被拒绝：修复后重试

7. 证明修复有效

• 强制要求： 对每项并行修复运行 /prove-fix
• 为每项变更构建代码证明轨迹并提供置信度评分
• 如果任何变更的评分低于 80%，则返回调试流程处理该修复

8. 最终报告

• 汇总所有并行阶段的修复
• 按问题列出验证状态（包括 prove-fix 置信度评分）
• 询问是否提交（若同意，则使用 git-manager）

示例： 修复 1（身份验证）+ 修复 2（支付）+ 修复 3（UI）→ 启动 3 个 fullstack-developer Agent → 等待 → 分别证明每项修复有效 → 按顺序处理修复 4（集成）

---

后续步骤（独立运行：必须通过 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 = 拆分。

• 强制要求：重要事项，务必注意：修复尝试失败 3 次后立即停止。报告所有尝试，并在继续前询问用户。

• 强制要求：重要事项，务必注意：进行任何 UI 更改前，阅读 frontend-patterns-reference、scss-styling-guide 和 design-system/README。