Back to Details

debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Debug Workflow Skill

Debug Workflow Skill

Overview

概述

Investigation-first workflow for debugging and regression fixes. Provides two tracks based on urgency: hotfix (fast, minimal ceremony) and thorough (rigorous, full RCA documentation).
以调查为核心的调试与回归修复工作流。根据紧急程度提供两种路径：热修复（快速、流程简化）和全面修复（严谨、包含完整RCA文档）。

Triggers

触发条件

Activate this skill when:
  • User runs 
    /debug
    command
  • User reports a bug or regression
  • User needs to investigate an error
  • User says "fix this bug" or similar
Disambiguation: If the user says "fix" or "clean up" — use 
/debug
when something is broken (error, crash, wrong behavior). Use 
/refactor
when the code works but needs structural improvement.
在以下场景激活此Skill：
  • 用户执行/debug命令
  • 用户报告Bug或回归问题
  • 用户需要调查错误
  • 用户说出"fix this bug"或类似表述
歧义消除： 如果用户提到"fix"或"clean up"——当功能出现故障（错误、崩溃、行为异常）时使用/debug；当代码可正常运行但需要结构优化时使用/refactor。

Workflow Overview

工作流概述

                              /debug
                                 │
                            ┌────┴────┐
                            │ Triage  │
                            └────┬────┘
                                 │
               ┌─────────────────┼─────────────────┐
               │                 │                 │
          --hotfix            (default)       --escalate
               │                 │                 │
               ▼                 ▼                 ▼
      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
      │  Hotfix Track  │  │   Thorough  │   │ /ideate  │
      │                │  │    Track    │   │ handoff  │
      └────────────────┘  └─────────────┘   └──────────┘
                              /debug
                                 │
                            ┌────┴────┐
                            │  分类排查  │
                            └────┬────┘
                                 │
               ┌─────────────────┼─────────────────┐
               │                 │                 │
          --hotfix            (默认)       --escalate
               │                 │                 │
               ▼                 ▼                 ▼
      ┌────────────────┐  ┌─────────────┐   ┌──────────┐
      │  热修复路径  │  │   全面修复  │   │ /ideate  │
      │                │  │    路径    │   │  移交  │
      └────────────────┘  └─────────────┘   └──────────┘

Command Interface

命令接口

Start Debug Workflow

启动调试工作流

bash
undefined
bash
undefined

Default: thorough track

默认：全面修复路径

/debug "Description of the bug"
/debug "Bug描述"

Fast path: hotfix track

快速路径：热修复路径

/debug --hotfix "Production is down - users can't login"
/debug --hotfix "生产环境宕机 - 用户无法登录"

Escalate to feature workflow

升级至功能开发工作流

/debug --escalate "This needs architectural changes"
undefined
/debug --escalate "此修复需要架构变更"
undefined

Mid-Workflow Commands

工作流中途命令

bash
undefined
bash
undefined

Switch from hotfix to thorough (during investigation)

从热修复路径切换至全面修复路径（调查过程中）

/debug --switch-thorough
/debug --switch-thorough

Escalate to /ideate (manual handoff)

升级至/ideate流程（手动移交）

/debug --escalate "Reason for escalation"
/debug --escalate "升级原因"

Resume after context compaction

上下文压缩后恢复工作流

/rehydrate
undefined
/rehydrate
undefined

Track Comparison

路径对比

AspectHotfixThorough
UrgencyP0 (production down)P1/P2 (normal priority)
Investigation15 min time-boxedNo time limit
RCA DocumentNo (minimal in state)Yes (full docs/rca/)
WorktreeNo (in-place fix)Yes (isolated)
ReviewSmoke test onlySpec review
Human Checkpoints1 (merge)1 (merge)
方面热修复全面修复
紧急程度P0（生产环境宕机）P1/P2（常规优先级）
调查时长限时15分钟无时间限制
RCA文档无（仅在状态中记录极简信息）有（完整文档存储于docs/rca/）
工作树无（原地修复）有（隔离环境）
审核仅冒烟测试规范审核
人工检查点1个（合并阶段）1个（合并阶段）

Decision Runbooks

决策手册

For track-selection criteria at the triage phase, query the decision runbook: 
exarchos_orchestrate({ action: "runbook", id: "triage-decision" })
For investigation escalation criteria, query: 
exarchos_orchestrate({ action: "runbook", id: "investigation-decision" })
These runbooks encode the structured decision trees for track selection. The agent reads the decision tree and follows the guidance — the platform does not execute branches.
如需了解分类排查阶段的路径选择标准，请查询决策手册： 
exarchos_orchestrate({ action: "runbook", id: "triage-decision" })
如需了解调查升级标准，请查询： 
exarchos_orchestrate({ action: "runbook", id: "investigation-decision" })
这些手册编码了路径选择的结构化决策树。Agent会读取决策树并遵循指引——平台不会执行分支逻辑。

Hotfix Track

热修复路径

Fix production issues ASAP. Speed over ceremony.
HSM phases: 
triage
→ 
investigate
(15 min max) → 
hotfix-implement
(no worktree) → 
hotfix-validate
→ 
completed
See 
references/triage-questions.md
for triage guidance.
尽快修复生产环境问题。优先速度，简化流程。
HSM阶段： 
triage
→ 
investigate
（最长15分钟）→ 
hotfix-implement
（无工作树）→ 
hotfix-validate
→ 
completed
分类排查指引请参考
references/triage-questions.md
。

Investigation Timer

调查计时器

  1. On hotfix track selection: record 
    investigation.startedAt
    in state
  2. After each major finding: check elapsed time
  3. At 15 min mark: emit 
    investigation.timeout
    event, pause for user confirmation
    • Switch to thorough track? (yes/no)
For detailed phase instructions, see 
references/hotfix-track.md
.
  1. 选择热修复路径后：在状态中记录
    investigation.startedAt
  2. 每次有重要发现后：检查已耗时
  3. 到达15分钟时限时：触发
    investigation.timeout
    事件，暂停并等待用户确认
    • 是否切换至全面修复路径？（是/否）
详细阶段说明请参考
references/hotfix-track.md
。

Thorough Track

全面修复路径

Fix bugs with proper rigor. Full RCA documentation.
HSM phases: 
triage
→ 
investigate
→ 
rca
→ 
design
→ 
debug-implement
(worktree + TDD) → 
debug-validate
→ 
debug-review
→ 
synthesize
→ 
completed
For detailed phase instructions, see 
references/thorough-track.md
. For systematic investigation methodology, see 
references/investigation-checklist.md
.
以严谨的方式修复Bug，包含完整的RCA文档。
HSM阶段： 
triage
→ 
investigate
→ 
rca
→ 
design
→ 
debug-implement
（工作树+TDD）→ 
debug-validate
→ 
debug-review
→ 
synthesize
→ 
completed
详细阶段说明请参考
references/thorough-track.md
。系统调查方法请参考
references/investigation-checklist.md
。

Characterization Testing (Thorough Track Only)

特征测试（仅全面修复路径）

Before fixing a bug in the thorough track, capture the buggy behavior as a characterization test:
  1. Before fix: Write a test that documents the current (buggy) behavior — it should PASS with the bug present
  2. Write the fix test: Write a test that describes the correct behavior — it should FAIL (this is the standard TDD RED phase)
  3. Apply the fix: Implement the fix. The fix test should now PASS, and the characterization test should now FAIL
  4. Verify: The characterization test failing confirms the bug is actually fixed. If it still passes, the fix didn't address the root cause.
This is not required for the hotfix track — hotfixes prioritize speed over documentation.
在全面修复路径中修复Bug前，需将错误行为捕获为特征测试：
  1. 修复前： 编写测试记录当前（错误）行为——Bug存在时测试应通过
  2. 编写修复测试： 编写测试描述正确行为——此时测试应失败（这是标准TDD的RED阶段）
  3. 应用修复： 实施修复。修复测试应转为通过，特征测试应转为失败
  4. 验证： 特征测试失败确认Bug已被修复。若仍通过，则修复未解决根本原因
热修复路径无需此步骤——热修复优先速度而非文档记录。

Track Switching

路径切换

  • Hotfix -> Thorough: When investigation timer expires (15 min). All findings preserved.
  • Thorough -> Escalate: When fix requires architectural changes. Hand off to 
    /ideate
    .
For detailed switching logic, see 
references/thorough-track.md
.
  • 热修复 → 全面修复： 调查计时器到期（15分钟）时触发。所有调查结果将被保留。
  • 全面修复 → 升级： 修复需要架构变更时触发。移交至/ideate流程。
详细切换逻辑请参考
references/thorough-track.md
。

Auto-Chain Behavior

自动链式行为

Both tracks have ONE human checkpoint before completion.
Hotfix auto-chain:
triage → investigate → hotfix-implement → [HUMAN: hotfix-validate] → completed
         (auto)        (auto)
Thorough auto-chain:
triage → investigate → rca → design → debug-implement → debug-validate → debug-review → [HUMAN: synthesize] → completed
         (auto)        (auto) (auto)   (auto)           (auto)            (auto)
两种路径在完成前均包含一个人工检查点。
热修复自动链：
triage → investigate → hotfix-implement → [人工环节: hotfix-validate] → completed
         (自动)        (自动)
全面修复自动链：
triage → investigate → rca → design → debug-implement → debug-validate → debug-review → [人工环节: synthesize] → completed
         (自动)        (自动) (自动)   (自动)           (自动)            (自动)

State Management

状态管理

Initialize debug workflow:
action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"
See 
@skills/debug/references/state-schema.md
for full schema.
初始化调试工作流：
action: "init", featureId: "debug-<issue-slug>", workflowType: "debug"
完整状态 schema 请参考
@skills/debug/references/state-schema.md
。

Phase Transitions and Guards

阶段转换与守卫条件

Every phase transition has a guard that must be satisfied. Before transitioning, consult 
@skills/workflow-state/references/phase-transitions.md
for the exact prerequisite for each guard.
每个阶段转换都有必须满足的守卫条件。转换前，请查阅
@skills/workflow-state/references/phase-transitions.md
获取每个守卫条件的确切前提。

Schema Discovery

Schema 发现

Use 
exarchos_workflow({ action: "describe", actions: ["set", "init"] })
for parameter schemas and 
exarchos_workflow({ action: "describe", playbook: "debug" })
for phase transitions, guards, and playbook guidance.
使用
exarchos_workflow({ action: "describe", actions: ["set", "init"] })
获取参数schema，使用
exarchos_workflow({ action: "describe", playbook: "debug" })
获取阶段转换、守卫条件和工作手册指引。

Integration Points

集成点

With /rehydrate

与/rehydrate集成

Debug workflows resume like feature workflows:
bash
/rehydrate
调试工作流与功能开发工作流的恢复方式一致：
bash
/rehydrate

With Existing Skills

与现有Skill集成

  • Uses spec-review skill for thorough track review phase
  • Uses synthesis skill for PR creation
  • Uses git-worktrees skill for thorough track implementation
  • 全面修复路径的审核阶段使用spec-review skill
  • PR创建使用synthesis skill
  • 全面修复路径的实施阶段使用git-worktrees skill

With MCP Workflow State Tools

与MCP工作流状态工具集成

Extended to support:
  • workflowType: "debug"
    field
  • Debug-specific phases handled by the SessionStart hook (which determines next action on resume)
  • Debug context provided by the SessionStart hook on session start
扩展支持：
  • workflowType: "debug"
    字段
  • 会话启动钩子（SessionStart hook）处理调试专属阶段（用于恢复时确定下一步操作）
  • 会话启动时由SessionStart钩子提供调试上下文

Completion Criteria

完成标准

Hotfix Complete

热修复完成

  • Root cause identified (even if briefly)
  • Minimal fix applied
  • Affected tests pass
  • Follow-up RCA task created
  • Changes merged
Completion guard shapes — set these via 
exarchos_workflow set
before transitioning to 
completed
:
Exit pathGuardRequired state
Direct push (no PR)
fix-verified-directly
resolution: { directPush: true, commitSha: "<sha>" }
Validation passed
validation-passed
validation: { passed: true }
Via PRThrough 
synthesize
→ 
completed
prUrl
must exist
  • 已确定根本原因（即使仅简要记录）
  • 已应用最小化修复
  • 受影响的测试已通过
  • 已创建后续RCA任务
  • 变更已合并
完成守卫条件 —— 转换至
completed
前，需通过
exarchos_workflow set
设置以下条件：
退出路径守卫条件必填状态
直接推送（无PR）
fix-verified-directly
resolution: { directPush: true, commitSha: "<sha>" }
验证通过
validation-passed
validation: { passed: true }
通过PR经
synthesize
→ 
completed
必须存在
prUrl

Thorough Complete

全面修复完成

  • Full RCA documented in docs/rca/ (use 
    references/rca-template.md
    )
  • Fix matches RCA findings
  • TDD implementation with tests
  • Spec review passed
  • PR merged
Completion guard shapes — the thorough track exits through 
synthesize
→ 
completed
(guard: 
pr-url-exists
, requires 
prUrl
in state).
  • 完整的RCA文档已存储于docs/rca/（使用
    references/rca-template.md
    模板）
  • 修复方案匹配RCA发现
  • 采用TDD方式实施并包含测试
  • 规范审核已通过
  • PR已合并
完成守卫条件 —— 全面修复路径通过
synthesize
→ 
completed
退出（守卫条件：
pr-url-exists
，状态中必须存在
prUrl
）。

Anti-Patterns

反模式

Don'tDo Instead
Start coding before understanding bugInvestigate first, always
Skip RCA on thorough trackDocument for future learning
Exceed 15 min on hotfix investigationSwitch to thorough track
Add features during bug fixScope creep - only fix the bug
Skip tests because "it's just a fix"Fixes need tests to prevent regression
禁止行为正确做法
未理解Bug就开始编码始终先进行调查
全面修复路径中跳过RCA记录文档以供后续学习
热修复调查时长超过15分钟切换至全面修复路径
Bug修复过程中添加新功能避免范围蔓延 - 仅修复Bug
以"只是个修复"为由跳过测试修复需要测试以防止回归

Troubleshooting

故障排查

See 
references/troubleshooting.md
for MCP tool failures, state desync, investigation timeouts, and track switching issues.
MCP工具故障、状态不同步、调查超时及路径切换问题的排查请参考
references/troubleshooting.md
。