fix-issue

name	fix-issue
description	以架构师视角分析并修复问题，强制 plan 模式，杜绝补丁式修复。涉及协议时严格按协议来，协议有问题则协议先行调整，代码再跟进。当遇到 Bug 反馈、错误日志或功能异常时使用。
argument-hint	<问题描述、错误日志或 Issue 链接> [--review <block|all|discuss>]
model	opus

Fix Issue — 架构级问题修复

以架构师视角系统性修复问题。核心原则：TDD 红绿灯 + 协议先行 + 杜绝补丁式修复。

---

Step 1：进入 Plan 模式 & Issue 状态推进

使用 EnterPlanMode 进入计划模式。所有分析和方案设计必须在 Plan 模式内完成，审批后才可编码。

1.1 Issue 状态推进（开始处理时）

如果输入中包含可追踪系统的 Issue，立即推进状态至"开发中"：

平台	识别特征	推进动作
Jira	PROJECT-N 或 Jira URL	使用 mcp__atlassian__getTransitionsForJiraIssue 获取可用状态，然后 mcp__atlassian__transitionJiraIssue 推进至"开发中"或类似状态（如 In Progress / In Development）
GitHub	owner/repo#N 或 URL	无内置状态机，跳过

1.2 父 Issue 阅读 —— 北极星校验（强制）

目的：当前 Issue 若隶属于某个父 Issue（Epic / Tracking Issue / Parent），父 Issue 承载了整体设计意图、范围边界与验收标准。修复决策必须服从父 Issue 的北极星方向，避免局部修复偏离整体架构。

检测父 Issue（覆盖常见结构）：

平台	父子关系载体	检测方式
GitHub	Sub-issues（原生）/ Parent: #N、Part of #N、Tracked by #N 等引用 / 同一 Milestone 下的 tracking issue / Task list checklist 反向引用	gh issue view <N> --json body,milestone,parent,trackedInIssues,subIssuesSummary；再看正文中对父 Issue 的显式引用
Jira	Epic Link / Parent Link / Sub-task 的 parent	mcp__atlassian__getJiraIssue 返回字段中的 parent / customfield_* Epic Link

执行动作：

1. 检测当前 Issue 是否存在父 Issue（至少检查 1 层直接父级；若有更高层 Epic，也一并读取）
2. 如果有父 Issue：读取父 Issue 的 标题、描述、验收标准、已关联子 Issue 列表、评论中的关键决策
3. 提炼父 Issue 的"北极星要素"：
   • 整体目标（解决什么本质问题）
   • 范围边界（哪些明确属于本次范围、哪些被排除）
   • 已定下的设计决策（架构选型、协议方向、兼容性约束）
   • 验收标准（父 Issue 层面的 Definition of Done）
4. 在后续 Step 2～Step 5 的每一次决策点，将方案与北极星要素对齐校验：
   • 根因分析是否与父 Issue 识别的本质问题一致？
   • 修复方案是否仍落在父 Issue 划定的范围内？
   • 是否违反父 Issue 已定下的架构/协议决策？
5. 如果没有父 Issue：记录"无父 Issue，以当前 Issue 自身为顶层范围"，跳过此子步骤
6. 如果父 Issue 与当前 Issue 方向冲突：停止修复，使用 AskUserQuestion 向用户确认——是父 Issue 需要拆分/调整，还是当前 Issue 归属有误

硬性规则：父 Issue 存在时，其已明确的设计决策优先级高于本 Issue 的局部修复直觉。如需偏离父 Issue 方向，必须显式与用户对齐。

---

Step 2：问题定位与根因分析（Plan 模式内）

2.1 理解问题

1. 分析问题描述，明确表象和可能的根因
2. 定位相关代码，找到涉及的所有文件和模块
3. 绘制影响范围：受影响的模块、调用链路

2.2 全链路追踪

根据当前项目类型追踪完整调用链。

按项目参见 {baseDir}/resources/<project>.md "调用链路追踪"章节。

2.3 区分问题层级

明确问题出在哪一层：

层级	说明
协议层	事件定义、数据结构、序列化格式与协议规范不符
传输层	Socket.IO 连接、重连、命名空间
业务层	各组件自身的逻辑错误
集成层	跨组件/跨项目的交互问题

2.4 根因分析

• 同类问题在其他模块是否也存在？
• 这是协议设计缺陷还是实现疏忽？
• 修补表面症状是否会在其他组件引发新问题？
• 排除误报：如果问题不存在或属于使用姿势问题，直接说明并结束

---

Step 3：协议合规门控（Plan 模式内）

当根因涉及协议时，此步骤为强制门控，不可跳过。

3.1 判定是否涉及协议

信号	判定
事件名/字段名/数据结构与协议规范不一致	涉及协议
错误码使用不符合协议定义	涉及协议
跨 SDK 行为不一致（Python vs Rust）	可能涉及协议
纯业务逻辑 Bug	不涉及协议

3.2 协议侧是否正确？

读取对应协议仓库的规范文档，与代码实现对比：

• A2C 协议：读取 a2c-smcp-protocol 的 docs/specification/ 下相关文件
• OASP 协议：读取 oasp-protocol 的 docs/specification/ 下相关文件

协议详情参见 skills/add-feature/resources/a2c.md 和 skills/add-feature/resources/oasp.md。

3.3 结果分支

结论	后续动作
代码不符合协议 → 代码有 Bug	继续 Step 4，按协议规范修复代码
协议本身有问题（设计缺陷/不完善）	停止代码修复，引导用户走 /add-feature 流程先调整协议，协议发布后再回来修代码
协议模糊/未覆盖此场景	使用 AskUserQuestion 与用户确认：是按现有理解修复，还是先明确协议？

硬性规则：代码仅可实现协议已定义的行为。如果修复需要改变协议语义，必须协议先行。

---

Step 3.6：用户体验影响澄清门控（写测试前，强制）

当变更触及用户可感知的交互时，此步骤为强制门控。 触发信号：UI 状态、操作步骤、命令行为、可见能力（skill / tool）出现/消失时机、默认行为等；纯内核 / 协议内部、无用户可感差异的变更豁免（豁免须在计划中显式说明）。

未经用户对「体验 before/after」做出判断并接受，不得进入 Step 4（写测试）/ Step 5-6（动代码）。与协议门控、隔离审查门控同级。用 AskUserQuestion 把「舞台 / 现状走查 / 改后走查 / 跨场景权衡 / 决策取景框」交用户拍板。

触发 / 豁免细则与场景化产出模板见单一源：{baseDir}/resources/ux-impact-gate.md。

---

Step 4：编写失败测试 — TDD 红灯（Plan 模式内规划，审批后执行）

在修改任何业务代码之前，必须先编写测试用例复现问题：

1. 确定测试文件位置（遵循项目测试目录约定）
2. 编写最小化测试用例，精确触发问题
3. 运行测试，确认测试失败，且失败原因与问题一致
4. 如果测试没有失败 → 回到 Step 2 重新分析

没有失败的测试，就不要开始修复。

测试命令按项目参见 {baseDir}/resources/<project>.md。

---

Step 5：方案设计（Plan 模式内）

5.1 设计原则（强制遵守）

• 根因修复：修复产生问题的根源，而非在调用处加特判/try-catch/绕过
• 复用优先：优先使用项目已有的工具和封装，增强现有工具而非新建
• 最小化变更：只修改与问题直接相关的代码，不做无关的重构
• 一致性：同模块其他功能是否有相同问题？批量修复，不留隐患
• 跨实现同步：涉及双实现（同步/异步、前端/后端）时必须同步更新

5.2 上游依赖问题

当根因在上游依赖时：不修改上游代码，输出 Bug Report；保留失败测试作为验收标准；仅在阻塞核心功能时添加临时适配（标注 // WORKAROUND: see #xxx）。

5.3 输出修复计划

• 问题确认结论（存在/不存在/部分存在）
• 根因说明（一句话）
• 根因归属（本项目 / 协议问题 / 上游依赖）
• 修改文件清单（每个文件的具体变更）
• 测试计划（复现测试 + 边界用例）
• 验证步骤

使用 ExitPlanMode 提交计划等待审批。未经用户确认不得开始编码。

---

Step 6：实施修复（审批后）

1. 先提交复现测试，确认红灯
2. 实现修复，按计划逐文件修改
3. 补充边界测试，关键场景增加用例

项目特有的架构原则和验证命令参见 {baseDir}/resources/<project>.md。

---

Step 7：验证（TDD 绿灯）

1. 运行复现测试，确认从红灯变绿灯
2. 运行全量测试套件，确认无回归
3. 运行lint / 类型检查，确认代码质量
4. 如涉及协议类型，确认跨 SDK 序列化兼容性

验证命令按项目参见 {baseDir}/resources/<project>.md。

---

Step 7.5：隔离审查硬门控（绿灯后强制）

全量绿灯后，禁止自评通过直接收尾。用 Agent 工具拉起隔离上下文的 a2c-smcp-toolkit:code-reviewer 子代理客观复审，按 --review 等级走 /fix-review，🔴 未清零不算修复完成。子代理拉起时须传入「问题意图」（根因结论 / 验收标准 / 父 Issue 北极星），不传实现自评。

流水线、--review 分级、琐碎豁免（含 --review none）见单一源：skills/code-review/resources/embedded-review-gate.md。

---

Step 8：总结、Issue 回复与状态推进

向用户汇报：根因、修复方式、变更文件、测试覆盖、架构影响。

Issue 回复 & 状态推进（如适用）

如果输入中包含可追踪系统的 Issue，验证通过后同时完成回复和状态推进：

平台	回复工具	状态推进
GitHub	gh issue comment	如适用可 gh issue close
Jira	mcp__atlassian__addCommentToJiraIssue	mcp__atlassian__transitionJiraIssue 推进至"已完成"或类似状态（如 Done / Resolved）

回复内容规范（≤300 字，面向外部用户，不暴露内部路径）：

## 修复说明

**根因**：[一句话描述问题的本质原因]

**修复内容**：
- [具体修改点 1]
- [具体修改点 2]

**验收方式**：
- [如何验证修复生效，如测试用例名、手动验证步骤]
- 新增测试 `[test_name]` 覆盖此场景，全量测试通过

**版本**：修复已合并至 `main`，将在 `vX.Y.Z` 中发布

---

强制约束

• 禁止无测试修复 — 每个修复必须有复现测试
• 禁止补丁式修复 — 不允许特判/绕过/吞异常
• 禁止绕过协议 — 协议有问题则协议先行
• 禁止跳过体验门控 — 变更触及用户可感交互时，未经用户对体验 before/after 拍板不得动代码（纯内核变更豁免）
• 禁止无确认实施 — 方案必须经用户审批
• 禁止重复封装 — 优先复用现有工具
• 禁止跳过独立审查 — 绿灯后必须经隔离上下文 code-reviewer 子代理复审，🔴 未清零不得收尾（琐碎改动可豁免）