Debug Issue 是一个系统化调试流程技能，核心理念是“先复现，后理论”——在存在失败命令之前形成的假设，只是伪装成计划的猜测。
用途 该技能用于系统性地调试一个症状，通过可产生红色（失败）结果的反馈回路、最小化复现、排序的可证伪假设、带标签的探针，以及回归测试来定位并修复问题。
主要能力与流程
阶段 0：争用与真实状态 在任何代码假设之前，先确认是否有其他进程、智能体、工作树或用户的其他工具正在触碰同一分支、数据库、端口、会话或共享凭据/令牌存储（如 git worktree list、lsof -i :<port>，或直接询问）。必须先排除这一点——争用下的不稳定行为看起来与代码缺陷完全一样，两个客户端刷新同一个轮换令牌会互相失效。在有读取权限时，先查看真实的失败记录、用户或任务状态（只读），这常常直接点明原因。绝不要盲目重试一个已部分失败的副作用调用（POST、发送、支付、迁移）：先读取远端状态，因为第一次尝试可能已半成功。
阶段 1：构建可产生红色结果的回路 构建一条命令——测试、curl、CLI + fixture、无头脚本、重放的 trace 或一次性 harness——并已运行过一次，且在当前确切症状上变红。它必须：断言用户的症状，而非“运行无报错”；确定性、秒级快速、无需用户即可由你运行；只打印脱敏输出：密钥变为 <REDACTED>，凭据保留在环境变量中，捕获的产物（HAR、请求转储）只在携带信号的行上引用。如果在命令存在之前就开始读代码构建理论，立即停止。没有可产生红色结果的命令，就没有假设。如果确实无法构建，说明情况、列出尝试过的方法，并请求环境、脱敏产物或插桩许可。
阶段 2：最小化 缩减到仍能变红的最小场景：逐一削减输入、调用方、配置、数据和步骤，每次削减后重新运行。当移除任何剩余元素都会使其变绿时即完成。最小复现缩小了假设空间，并成为回归测试。
阶段 3：排序的可证伪假设 在测试任何假设之前生成 3–5 个假设——只锚定第一个看似合理的想法会导致偏差。对于固定输入下的一次性失败，将“运行之间什么在变化”排高：时钟并列、无序读取（ORDER BY 未以唯一列结尾）、并发、缓存或重试状态。每个假设必须陈述预测：“如果 X 是原因，那么改变 Y 会使缺陷消失 / 改变 Z 会使其更糟。”无法陈述预测意味着只是感觉：要么锐化，要么丢弃。在探测前向用户展示排序列表（他们凭领域知识可瞬间重排）；如果用户不在，不要阻塞等待。
图加速器（可选，当 codegraph 索引就绪时）：codegraph explore "<symptom>"（或 codegraph_explore）、codegraph callers|callees <symbol>、codegraph affected <recently changed files> 用于回归、codegraph impact <symbol> 在触碰共享代码前使用。没有它们时：rg、测试、日志、运行时探针。
阶段 4：一次探测一个变量 每个探针映射到阶段 3 的一个预测。将每个被证伪的假设和每个失败的修复记录为 MEMORY.md 中的一行（在 safe-code 下的 SESSION.md 中起草），以免他人重跑。为每个临时日志打上唯一前缀标签，例如 [DEBUG-a4f2]，以便清理时一次 grep 完成。优先使用调试器或 REPL 断点，而非十条日志；绝不要“记录一切再 grep”。
阶段 5：在正确的接缝处修复 在修复之前先写回归测试，接缝应使测试能复现调用点处真实发生的缺陷模式。接缝太浅（单元测试无法复现触发缺陷的链路）会带来虚假信心。如果不存在正确的接缝，这本身就是一个发现：记录到 MEMORY.md——架构正在阻止该缺陷被锁定。然后只修补最小的已确认原因。
清理门（在宣布完成之前） 原始复现不再复现（运行它，不要假设）；回归测试曾在无修复时失败（就地绕过修复 -> 红 -> 恢复；在共享检出中不要做破坏性 git 操作——参见 safe-code 技能的 references/multi-session.md 共享检出规则）并在有修复时通过，或者记录接缝缺失——从未见过红色的测试证明不了任何东西；grep -rn "[DEBUG-" <src> 为空，一次性 harness 已删除；清理只关闭本任务打开的窗口、标签页、守护进程和锁——绝不关闭用户的；只有在证明没有活动进程持有陈旧锁后才移除它；在提交信息中陈述获胜假设，以便下一位调试者学习。
输出 以以下内容开头：根因（存活的假设，以及哪个预测确认了它）· 更改的文件 · 可产生红色结果的命令及其前后结果 · 剩余风险或缺失覆盖（包括“无正确接缝”）。
适用场景 适用于需要严谨定位缺陷的软件开发与调试工作，尤其是涉及并发、状态、副作用调用、回归测试和共享代码库的场景。
限制 该技能要求能够构建可产生红色结果的反馈回路；如果无法构建，需明确说明并请求环境、脱敏产物或插桩许可。它强调不得盲目重试副作用调用，不得在共享检出中做破坏性 git 操作，且清理时不得关闭用户打开的窗口、标签页、守护进程和锁。