| 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 |
执行动作：
- 检测当前 Issue 是否存在父 Issue（至少检查 1 层直接父级；若有更高层 Epic，也一并读取）
- 如果有父 Issue：读取父 Issue 的 标题、描述、验收标准、已关联子 Issue 列表、评论中的关键决策
- 提炼父 Issue 的"北极星要素"：
- 整体目标（解决什么本质问题）
- 范围边界（哪些明确属于本次范围、哪些被排除）
- 已定下的设计决策（架构选型、协议方向、兼容性约束）
- 验收标准（父 Issue 层面的 Definition of Done）
- 在后续 Step 2～Step 5 的每一次决策点，将方案与北极星要素对齐校验：
- 根因分析是否与父 Issue 识别的本质问题一致？
- 修复方案是否仍落在父 Issue 划定的范围内？
- 是否违反父 Issue 已定下的架构/协议决策？
- 如果没有父 Issue：记录"无父 Issue，以当前 Issue 自身为顶层范围"，跳过此子步骤
- 如果父 Issue 与当前 Issue 方向冲突：停止修复，使用 AskUserQuestion 向用户确认——是父 Issue 需要拆分/调整，还是当前 Issue 归属有误
硬性规则：父 Issue 存在时，其已明确的设计决策优先级高于本 Issue 的局部修复直觉。如需偏离父 Issue 方向，必须显式与用户对齐。
Step 2：问题定位与根因分析（Plan 模式内）
2.1 理解问题
- 分析问题描述，明确表象和可能的根因
- 定位相关代码，找到涉及的所有文件和模块
- 绘制影响范围：受影响的模块、调用链路
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 模式内规划，审批后执行）
在修改任何业务代码之前，必须先编写测试用例复现问题：
- 确定测试文件位置（遵循项目测试目录约定）
- 编写最小化测试用例，精确触发问题
- 运行测试，确认测试失败，且失败原因与问题一致
- 如果测试没有失败 → 回到 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：实施修复（审批后）
- 先提交复现测试，确认红灯
- 实现修复，按计划逐文件修改
- 补充边界测试，关键场景增加用例
项目特有的架构原则和验证命令参见 {baseDir}/resources/<project>.md。
Step 7：验证（TDD 绿灯）
- 运行复现测试，确认从红灯变绿灯
- 运行全量测试套件，确认无回归
- 运行lint / 类型检查，确认代码质量
- 如涉及协议类型，确认跨 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 子代理复审，🔴 未清零不得收尾（琐碎改动可豁免）
