debug

调试工作流技能

概述

以调查为先的调试和回归修复工作流。根据紧急程度提供两种路径：热修复（快速、流程精简）和彻底修复（严格、完整记录根因分析）。

触发条件

在以下情况激活此技能：

• 用户运行 debug 命令
• 用户报告 Bug 或回归问题
• 用户需要调查错误
• 用户说“修复这个 Bug”或类似的话

**区分说明：**如果用户说“修复”或“清理”，当有内容出故障（错误、崩溃、行为异常）时，使用 debug。当代码可以正常工作但需要改进结构时，使用 refactor。

工作流概览

                              debug
                                 │
                            ┌────┴────┐
                            │ Triage  │
                            └────┬────┘
                                 │
               ┌─────────────────┼─────────────────┐
               │                 │                 │
          --hotfix            (default)       --escalate
               │                 │                 │
               ▼                 ▼                 ▼
      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
      │  Hotfix Track  │  │   Thorough  │   │ ideate  │
      │                │  │    Track    │   │ handoff  │
      └────────────────┘  └─────────────┘   └──────────┘

命令接口

启动调试工作流

# Default: thorough track
debug "Description of the bug"

# Fast path: hotfix track
debug --hotfix "Production is down - users can't login"

# Escalate to feature workflow
debug --escalate "This needs architectural changes"

工作流中途命令

# Switch from hotfix to thorough (during investigation)
debug --switch-thorough

# Escalate to ideate (manual handoff)
debug --escalate "Reason for escalation"

# Resume after context compaction
rehydrate <featureId>

路径对比

方面	热修复	彻底修复
紧急程度	P0（生产环境中断）	P1/P2（正常优先级）
调查	限时 15 分钟	不限时
根因分析文档	否（状态中仅作简要记录）	是（完整的 docs/rca/ 文档）
工作树	否（就地修复）	是（隔离环境）
审查	仅冒烟测试	规格审查
人工检查点	1 个（合并）	1 个（合并）

决策手册

在分流阶段选择路径时，请查询决策手册： exarchos_orchestrate({ action: "runbook", id: "triage-decision" })

有关调查升级标准，请查询： exarchos_orchestrate({ action: "runbook", id: "investigation-decision" })

这些手册包含结构化的路径选择决策树。Agent 会读取决策树并遵循指导，平台不会执行决策分支。

何时使用 debug，何时使用 refactor

信号	使用 debug	使用 refactor
某些内容出故障或行为异常	是	否
代码可以正常工作，但杂乱或复杂	否	是
用户报告 Bug 或回归问题	是	否
性能下降	从 debug 开始（调查）	如果问题源于结构，则升级到 refactor
“这应该重新组织一下”	否	是
生产日志中出现错误	是	否

**经验法则：**如果存在_症状_（某些本应正常工作的内容却无法正常工作），请使用 debug。如果只是对正常工作的代码_不满意_（难以阅读、违反 SOLID、逻辑重复），请使用 refactor。

热修复路径

尽快修复生产问题。速度优先，不拘泥于流程。

HSM 阶段：triage → investigate（最多 15 分钟）→ hotfix-implement（不使用工作树）→ hotfix-validate → completed

分流指导请参阅 references/triage-questions.md。

调查计时器

1. 选择热修复路径时：在状态中记录 investigation.startedAt
2. 每次有重大调查发现后：检查经过的时间
3. 到达 15 分钟时：发出 investigation.timeout 事件，并暂停以等待用户确认
   • 是否切换到彻底修复路径？（是/否）

详细阶段说明请参阅 references/hotfix-track.md。

彻底修复路径

严谨地修复 Bug。完整记录根因分析。

HSM 阶段：triage → investigate → rca → design → debug-implement（工作树 + TDD）→ debug-validate → debug-review → synthesize → completed

详细阶段说明请参阅 references/thorough-track.md。系统化调查方法请参阅 references/investigation-checklist.md。

设计阶段约束（全面流程：rca + 设计阶段）

rca 和 design 阶段是全面流程在设计时的工作界面。在这些阶段——确定修复方案之前——根据与修复相关的架构不变量，呈现 Constraints 部分。这相当于调试设计阶段中的 /ideate Phase 0，并且使用同一个共享事实来源来确定选择规则和目录注册门控条件：参见 @skills/ideate/references/constraint-anchoring.md。加载 .exarchos/invariants.md（cost-of-load: always-load 条目）并输出 Constraints 部分。**受目录注册门控：**如果 .exarchos.yml: invariants.catalogs 下没有注册目录，则不显示 Constraints 部分，直接继续。hotfix 流程跳过此步骤（速度优先于流程）。

特征化测试（仅限全面流程）

在全面流程中修复错误之前，先通过特征化测试记录错误行为：

1. **修复前：**编写一个记录当前（错误）行为的测试——存在错误时，该测试应当通过
2. **编写修复测试：**编写一个描述正确行为的测试——该测试应当失败（这是标准 TDD 的 RED 阶段）
3. **应用修复：**实施修复。现在修复测试应当通过，而特征化测试应当失败
4. **验证：**特征化测试失败即可确认错误确实已修复。如果测试仍然通过，说明修复没有解决根本原因。

hotfix 流程不要求此步骤——hotfix 优先追求速度，而非文档记录。

流程切换

• **Hotfix -> 全面流程：**调查计时器到期时（15 分钟）。保留所有发现。
• **全面流程 -> 升级：**修复需要架构变更时。交接给 ideate。

详细的切换逻辑请参见 references/thorough-track.md。

自动串联行为

两种流程都只有一个完成人工检查点。

Hotfix 自动串联：

triage → investigate → hotfix-implement → [HUMAN: hotfix-validate] → completed
         (auto)        (auto)

全面流程自动串联：

triage → investigate → rca → design → debug-implement → debug-validate → debug-review → [HUMAN: synthesize] → completed
         (auto)        (auto) (auto)   (auto)           (auto)            (auto)

状态管理

初始化调试工作流：

action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"

完整架构请参见 @skills/debug/references/state-schema.md。

阶段转换与守卫条件

每次阶段转换都必须满足一个守卫条件。转换前，请查阅 @skills/checkpoint/references/phase-transitions.md，了解每个守卫条件的确切前置要求。

架构发现

使用 exarchos_workflow({ action: "describe", actions: ["update", "init"] }) 获取参数架构，使用 exarchos_workflow({ action: "describe", playbook: "debug" }) 获取阶段转换、守卫条件和操作手册指南。

集成点

与 rehydrate 集成

调试工作流像功能工作流一样恢复：

rehydrate <featureId>

与现有技能集成

• 全面流程的 review 阶段使用 spec-review 技能
• 创建 PR 时使用 synthesis 技能
• 全面流程的实现阶段使用 git-worktrees 技能

与 MCP 工作流状态工具集成

扩展支持：

• workflowType: "debug" 字段
• rehydrate <featureId> 提供的调试专属阶段（恢复时的下一个动词由恢复文档的 next_actions 信封决定）
• 会话开始时通过 rehydrate <featureId> 提供调试上下文（无隐式钩子）

完成标准

Hotfix 完成

• 已确定根本原因（即使只是简要说明）
• 已应用最小化修复
• 受影响的测试通过
• 已创建后续 RCA 任务
• 已合并更改

完成守卫条件格式——在转换到 completed 之前，通过 exarchos_workflow update 设置以下内容：

退出路径	守卫条件	必需状态
直接推送（无 PR）	fix-verified-directly	resolution: { directPush: true, commitSha: "<sha>" }
验证通过	validation-passed	validation: { passed: true }
通过 PR	经过 synthesize → completed	必须存在 prUrl

全面完成

• 在 docs/rca/ 中记录完整的 RCA（使用 references/rca-template.md）
• 修复与 RCA 结论一致
• 采用 TDD 实现并编写测试
• 规格审查通过
• PR 已合并

完成守卫形状 — 全面流程通过 synthesize → completed 退出（守卫：pr-url-exists，要求状态中包含 prUrl）。

反模式

不要	应当
未弄清楚 Bug 就开始编码	始终先调查
在全面流程中跳过 RCA	记录下来，供日后学习
在热修复调查上花费超过 15 min	切换到全面流程
修复 Bug 时添加功能	避免范围蔓延——只修复 Bug
因为“只是修复一下”就跳过测试	修复需要测试以防止回归

故障排除

有关 MCP 工具故障、状态不同步、调查超时和流程切换问题，请参阅 references/troubleshooting.md。