systematic-debugging
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSystematic Debugging Skill
系统化调试技能
Operator Context
操作场景
This skill operates as an operator for systematic debugging workflows, configuring Claude's behavior for rigorous, evidence-based root cause analysis. It implements the Iterative Refinement architectural pattern — form hypothesis, test, refine, verify — with Domain Intelligence embedded in the debugging methodology.
该技能作为系统化调试工作流的操作指引，配置Claude的行为以进行严谨的、基于证据的根本原因分析。它在调试方法中嵌入了领域智能，实现了「迭代优化」架构模式——提出假设、测试、优化、验证。
Hardcoded Behaviors (Always Apply)
硬编码行为（始终生效）
- CLAUDE.md Compliance: Read and follow repository CLAUDE.md before debugging
- Over-Engineering Prevention: Fix only the bug. No speculative improvements, no "while I'm here" changes
- Reproduce First: NEVER attempt fixes before creating reliable reproduction
- No Random Changes: Every modification must be based on evidence from isolation
- Evidence Required: Every hypothesis must be tested with concrete evidence
- Verify Fixes: Confirm fix works AND doesn't introduce regressions
- 遵循CLAUDE.md规范：调试前阅读并遵循仓库中的CLAUDE.md
- 避免过度设计：仅修复bug，不进行推测性改进，不做「顺手修改」
- 先重现问题：在创建可靠的重现案例前，绝不尝试修复
- 禁止无据修改：所有修改必须基于隔离阶段得到的证据
- 需有证据支撑：所有假设必须通过具体证据验证
- 验证修复效果：确认修复有效且不会引入回归问题
Default Behaviors (ON unless disabled)
默认行为（默认开启，可关闭）
- Minimal Reproduction: Create smallest possible test case that shows bug
- Bisection Strategy: Use binary search to narrow down failure point
- One Change at a Time: Never make multiple changes simultaneously
- Document Findings: Log all observations, hypotheses, and test results
- Related Issues Check: Search for similar bugs in codebase and git history
- Temporary File Cleanup: Remove debug logs and profiling output at completion
- 最小化重现案例：创建能复现bug的最小测试用例
- 二分法策略：使用二分法缩小故障点范围
- 单次单一修改：绝不同时进行多项修改
- 记录调查结果：记录所有观察结果、假设和测试结果
- 检查相关问题：在代码库和Git历史中搜索类似bug
- 清理临时文件：完成调试后移除调试日志和性能分析输出
Optional Behaviors (OFF unless enabled)
可选行为（默认关闭，可开启）
- Regression Test Creation: Write automated test for this specific bug
- Git Bisect: Use to find breaking commit
git bisect - Performance Profiling: Run profiler to identify bottlenecks
- Database Query Analysis: Use EXPLAIN for slow query debugging
- Network Tracing: Capture traffic for API debugging
- 创建回归测试：为此特定bug编写自动化测试
- 使用Git Bisect：通过定位导致问题的提交
git bisect - 性能分析：运行分析工具识别性能瓶颈
- 数据库查询分析：使用EXPLAIN调试慢查询
- 网络追踪：捕获流量以调试API问题
What This Skill CAN Do
该技能可实现的功能
- Systematically find root causes through evidence-based investigation
- Create minimal reproductions that isolate the exact failure
- Distinguish between symptoms and root causes
- Verify fixes don't introduce regressions
- Document findings for future reference
- 通过基于证据的调查系统性地找到根本原因
- 创建能精确定位故障的最小化重现案例
- 区分症状与根本原因
- 验证修复不会引入回归问题
- 记录调查结果以备未来参考
What This Skill CANNOT Do
该技能无法实现的功能
- Fix bugs without first reproducing them
- Make speculative changes without evidence
- Optimize performance (use performance-optimization-engineer instead)
- Refactor code (use systematic-refactoring instead)
- Skip any of the 4 phases
- 未重现问题就修复bug
- 无证据支撑的推测性修改
- 性能优化（请使用performance-optimization-engineer技能）
- 代码重构（请使用systematic-refactoring技能）
- 跳过四个阶段中的任何一个
Instructions
操作步骤
Phase 1: REPRODUCE
阶段1：重现（REPRODUCE）
Goal: Establish consistent reproduction before attempting any fix.
Step 1: Document the bug
markdown
undefined目标：在尝试任何修复前，建立可稳定复现的案例。
步骤1：记录bug信息
markdown
undefinedBug: [Brief Description]
Bug：[简要描述]
Expected: [What should happen]
Actual: [What actually happens]
Environment: [OS, language version, dependencies]
**Step 2: Create minimal reproduction**
- Strip to essentials — remove unrelated code
- Use smallest dataset that shows the bug
- Isolate from external services where possible
**Step 3: Verify consistency**
Run reproduction **3 times**. If inconsistent, identify variables (timing, randomness, concurrency) and add controls to make it deterministic.
**Gate**: Bug reproduces 100% with documented steps. Proceed only when gate passes.预期结果：[应该发生的情况]
实际结果：[实际发生的情况]
环境信息：[操作系统、语言版本、依赖项]
**步骤2：创建最小化重现案例**
- 精简至核心内容——移除无关代码
- 使用能复现bug的最小数据集
- 尽可能与外部服务隔离
**步骤3：验证重现一致性**
运行重现案例**3次**。如果结果不一致，识别变量（时序、随机性、并发）并添加控制以使其可确定。
**准入条件**：通过记录的步骤可100%重现bug。仅当满足条件时才可进入下一阶段。Phase 2: ISOLATE
阶段2：隔离（ISOLATE）
Goal: Reduce search space by eliminating irrelevant code paths.
Step 1: List components involved in the failure
markdown
undefined目标：通过排除无关代码路径缩小搜索范围。
步骤1：列出涉及故障的组件
markdown
undefinedComponents
组件列表
- [Component A] - [Role]
- [Component B] - [Role]
- [Component C] - [Role]
**Step 2: Binary search**
Test components in combinations to find minimal failing set:
- A alone → PASS/FAIL?
- A + B → PASS/FAIL?
- A + B + C → PASS/FAIL?
When adding a component causes failure, that component (or its interaction) contains the bug.
**Step 3: Trace execution path**
Add targeted logging at decision points in the suspect component. Run and analyze:
- Where does execution diverge from expected?
- What values are unexpected at critical points?
- Are exceptions being caught silently?
**Gate**: Identified smallest code path and input that reproduces the bug. Proceed only when gate passes.- [组件A] - [作用]
- [组件B] - [作用]
- [组件C] - [作用]
**步骤2：二分法排查**
组合测试组件以找到最小故障集合：
- 仅组件A → 正常/故障？
- 组件A + B → 正常/故障？
- 组件A + B + C → 正常/故障？
当添加某个组件后出现故障，说明该组件（或其交互逻辑）存在bug。
**步骤3：追踪执行路径**
在可疑组件的决策点添加针对性日志，运行并分析：
- 执行路径与预期何处出现偏差？
- 关键节点的哪些值不符合预期？
- 是否有异常被静默捕获？
**准入条件**：已定位到能重现bug的最小代码路径和输入。仅当满足条件时才可进入下一阶段。Phase 3: IDENTIFY
阶段3：识别（IDENTIFY）
Goal: Determine exact root cause through hypothesis testing.
Step 1: Form hypothesis
markdown
undefined目标：通过假设测试确定确切的根本原因。
步骤1：提出假设
markdown
undefinedHypothesis: [Specific, testable statement]
假设：[具体、可测试的陈述]
Evidence: [What observations support this]
Test: [How to confirm or refute]
**Step 2: Test hypothesis**
Design a single, targeted experiment. Run it. Document result as CONFIRMED or REFUTED.
If REFUTED: Form new hypothesis based on what you learned. Return to Step 1.
**Step 3: Inspect suspect code**
Code inspection checklist:
- [ ] Off-by-one errors?
- [ ] Null/None values unhandled?
- [ ] Exceptions caught silently?
- [ ] Race conditions possible?
- [ ] Resources released properly?
- [ ] Input assumptions violated?
**Step 4: Verify root cause with targeted fix**
Make the smallest possible change that addresses the identified cause. Test against reproduction.
**Gate**: Root cause identified with evidence. Targeted fix resolves the issue. Can explain WHY bug occurred.证据：[支持该假设的观察结果]
测试方案：[验证或推翻假设的方法]
**步骤2：测试假设**
设计单一、针对性的实验并执行，记录结果为「已确认」或「已推翻」。
如果假设被推翻：基于所得信息提出新假设，返回步骤1。
**步骤3：检查可疑代码**
代码检查清单：
- [ ] 是否存在差一错误？
- [ ] 是否未处理Null/None值？
- [ ] 是否有异常被静默捕获？
- [ ] 是否存在竞态条件？
- [ ] 资源是否已正确释放？
- [ ] 输入是否违反了假设条件？
**步骤4：通过针对性修复验证根本原因**
做出解决已识别原因的最小修改，在重现案例上测试。
**准入条件**：已通过证据确定根本原因，针对性修复解决了问题，且能解释bug发生的原因。Phase 4: VERIFY
阶段4：验证（VERIFY）
Goal: Confirm fix works and doesn't introduce regressions.
Step 1: Run original reproduction steps → all pass
Step 2: Test edge cases (empty input, boundary values, null, maximum)
Step 3: Run full test suite → no regressions
Step 4: Test related functionality using similar patterns
Step 5: Create regression test (if optional behavior enabled)
python
def test_regression_[issue]():
"""Root cause: [what was wrong]. Fix: [what changed]."""
result = fixed_function(trigger_input)
assert result == expectedStep 6: Document fix summary
markdown
undefined目标：确认修复有效且不会引入回归问题。
步骤1：运行原始重现步骤 → 全部通过
步骤2：测试边缘情况（空输入、边界值、Null、最大值）
步骤3：运行完整测试套件 → 无回归问题
步骤4：测试使用类似模式的相关功能
步骤5：创建回归测试（若开启可选行为）
python
def test_regression_[issue]():
"""根本原因：[问题所在]。修复方案：[修改内容]。"""
result = fixed_function(trigger_input)
assert result == expected步骤6：记录修复摘要
markdown
undefinedFix Summary
修复摘要
Bug: [description]
Root Cause: [exact cause]
Fix: [changes made]
Files: [modified files]
Testing: reproduction passes, edge cases pass, full suite passes
**Gate**: All verification steps pass. Fix is complete.
---Bug：[描述]
根本原因：[确切原因]
修复方案：[修改内容]
涉及文件：[修改的文件]
测试情况：重现案例通过、边缘情况通过、完整测试套件通过
**准入条件**：所有验证步骤通过，修复完成。
---Examples
示例
Example 1: Test Failure
示例1：测试失败
User says: "Tests are failing after my last commit"
Actions:
- Run failing tests, capture output (REPRODUCE)
- Identify which test(s) fail, isolate to single test (ISOLATE)
- Trace test execution, form hypothesis about failure (IDENTIFY)
- Fix and verify all tests pass (VERIFY) Result: Root cause found, fix verified, no regressions
用户反馈：「我的上次提交后测试失败了」
操作步骤：
- 运行失败的测试并捕获输出（重现阶段）
- 确定哪些测试失败，隔离到单个测试（隔离阶段）
- 追踪测试执行路径，提出关于失败原因的假设（识别阶段）
- 修复并验证所有测试通过（验证阶段） 结果：找到根本原因，修复已验证，无回归问题
Example 2: Production Bug
示例2：生产环境Bug
User says: "Users are getting 500 errors on the checkout page"
Actions:
- Reproduce the 500 error locally with same inputs (REPRODUCE)
- Isolate to specific handler/middleware/service (ISOLATE)
- Identify which code path raises the error (IDENTIFY)
- Fix, test edge cases, verify no regressions (VERIFY) Result: Production fix with regression test
用户反馈：「用户在结账页面收到500错误」
操作步骤：
- 使用相同输入在本地重现500错误（重现阶段）
- 隔离到特定处理器/中间件/服务（隔离阶段）
- 确定引发错误的代码路径（识别阶段）
- 修复、测试边缘情况、验证无回归问题（验证阶段） 结果：生产环境问题已修复，并添加了回归测试
Error Handling
错误处理
Error: "Cannot Reproduce Bug"
错误：「无法重现Bug」
Cause: Environmental differences, timing-dependent, or randomness
Solution:
- Match environment exactly (OS, versions, dependencies)
- Look for race conditions or async timing issues
- Introduce determinism (fixed seeds, mocked time)
- If intermittent: add monitoring to catch it in-flight
原因：环境差异、时序依赖或随机性
解决方案：
- 完全匹配环境（操作系统、版本、依赖项）
- 检查是否存在竞态条件或异步时序问题
- 引入确定性（固定随机种子、模拟时间）
- 如果是间歇性问题：添加监控以实时捕获
Error: "Fix Breaks Other Tests"
错误：「修复导致其他测试失败」
Cause: Tests relied on buggy behavior, or fix changed API contract
Solution:
- If tests expected buggy behavior → update tests
- If fix exposed other bugs → apply 4-phase process to each
- If API changed → restore compatibility or update all callers
原因：测试依赖于buggy行为，或修复改变了API契约
解决方案：
- 如果测试预期buggy行为 → 更新测试
- 如果修复暴露了其他bug → 对每个问题应用四阶段流程
- 如果API发生变化 → 恢复兼容性或更新所有调用方
Error: "Root Cause Still Unclear After Isolation"
错误：「隔离后仍无法确定根本原因」
Cause: Isolation not narrow enough, or multiple contributing factors
Solution:
- Return to Phase 2 with narrower scope
- Add logging at lower abstraction levels
- Use debugger to step through execution
- Consult for common patterns
references/debugging-patterns.md
原因：隔离范围不够窄，或存在多个影响因素
解决方案：
- 回到阶段2，缩小范围
- 在更低抽象层级添加日志
- 使用调试器单步执行
- 参考中的常见模式
references/debugging-patterns.md
Anti-Patterns
反模式
Anti-Pattern 1: Fixing Without Reproducing
反模式1：未重现就修复
What it looks like: "Let me add better error handling" before seeing the actual error
Why wrong: Can't verify fix works, may fix wrong issue
Do instead: Complete Phase 1 first. Always.
表现：「我来添加更好的错误处理」，但尚未看到实际错误
危害：无法验证修复是否有效，可能修复了错误的问题
正确做法：先完成阶段1，始终如此
Anti-Pattern 2: Random Changes Without Evidence
反模式2：无据随机修改
What it looks like: "Maybe if I change this timeout..." without data
Why wrong: May mask symptom while leaving root cause. Can't explain why it works.
Do instead: Form hypothesis → test → confirm/refute → iterate
表现：「也许我改下超时时间试试...」，但无数据支撑
危害：可能掩盖症状但保留根本原因，无法解释修复生效的原因
正确做法：提出假设 → 测试 → 确认/推翻 → 迭代
Anti-Pattern 3: Multiple Changes at Once
反模式3：同时进行多项修改
What it looks like: Adding null check + fixing loop + wrapping in try/catch simultaneously
Why wrong: Can't determine which change fixed it. Introduces unnecessary code.
Do instead: One change, one test. Repeat until fixed.
表现：同时添加空值检查、修复循环、包裹try/catch
危害：无法确定是哪项修改解决了问题，引入不必要的代码
正确做法：单次单一修改，单次单一测试，重复直到修复完成
Anti-Pattern 4: Insufficient Verification
反模式4：验证不充分
What it looks like: "Specific test passes, ship it!" without running full suite
Why wrong: May have introduced regressions or missed edge cases
Do instead: Complete all Phase 4 steps before declaring done.
表现：「特定测试通过了，发布吧！」，但未运行完整测试套件
危害：可能引入回归问题或遗漏边缘情况
正确做法：完成阶段4的所有步骤后再宣布完成
Anti-Pattern 5: Undocumented Root Cause
反模式5：未记录根本原因
What it looks like: with no explanation
Why wrong: Bug will reappear. No institutional knowledge preserved.
Do instead: Document root cause, fix, and create regression test.
git commit -m "Fixed bug"表现：，无任何解释
危害：Bug可能再次出现，无法保留团队知识
正确做法：记录根本原因、修复方案并创建回归测试
git commit -m "Fixed bug"References
参考资料
This skill uses these shared patterns:
- Anti-Rationalization - Prevents shortcut rationalizations
- Verification Checklist - Pre-completion checks
该技能使用以下共享模式：
- 反合理化 - 防止捷径式合理化
- 验证清单 - 完成前检查
Domain-Specific Anti-Rationalization
领域特定反合理化
| Rationalization | Why It's Wrong | Required Action |
|---|---|---|
| "I can see the bug, no need to reproduce" | Visual inspection misses edge cases | Run reproduction 3 times |
| "This is probably the fix" | Probably ≠ proven | Form hypothesis, test with evidence |
| "Tests pass, must be fixed" | Specific test ≠ full suite | Run full test suite |
| "Simple change, no need to verify" | Simple changes cause complex regressions | Complete Phase 4 |
| 合理化借口 | 错误原因 | 要求操作 |
|---|---|---|
| 「我能看到bug，不需要重现」 | 视觉检查会遗漏边缘情况 | 运行重现案例3次 |
| 「这可能就是修复方案」 | 可能≠已证实 | 提出假设，用证据测试 |
| 「测试通过了，肯定修复了」 | 特定测试≠完整测试套件 | 运行完整测试套件 |
| 「修改很简单，不需要验证」 | 简单修改可能导致复杂的回归问题 | 完成阶段4的所有步骤 |
Reference Files
参考文件
- : Common bug patterns by category
${CLAUDE_SKILL_DIR}/references/debugging-patterns.md - : Language-specific debugging tools
${CLAUDE_SKILL_DIR}/references/tools.md - : Advanced isolation strategies
${CLAUDE_SKILL_DIR}/references/isolation-techniques.md
- ：按类别划分的常见bug模式
${CLAUDE_SKILL_DIR}/references/debugging-patterns.md - ：特定语言的调试工具
${CLAUDE_SKILL_DIR}/references/tools.md - ：高级隔离策略
${CLAUDE_SKILL_DIR}/references/isolation-techniques.md
Persistent Debug File Protocol
持久化调试文件协议
Debugging sessions lose all state on context reset — hypotheses, eliminated causes, evidence, and next actions vanish. This protocol creates a structured file that survives resets and lets a new session resume without re-investigating eliminated causes.
调试会话会在上下文重置时丢失所有状态——假设、已排除的原因、证据和下一步操作都会消失。该协议创建一个结构化文件，可在重置后保存状态，让新会话无需重新调查已排除的原因即可继续。
File: .debug-session.md
.debug-session.md文件：.debug-session.md
.debug-session.mdCreate this file at the start of every debug investigation. It has three section types with strict mutation rules:
| Section Type | Sections | Mutation Rule | WHY |
|---|---|---|---|
| IMMUTABLE | Symptoms, Reproduction Steps | Write once at session start, never modify | These are the ground truth. If they change, it's a different bug. Editing them mid-investigation causes you to lose track of the original problem. |
| APPEND-ONLY | Evidence, Eliminated Hypotheses | Add new entries, never remove or edit existing ones | Removing entries lets future sessions re-investigate dead ends. The whole point is to accumulate knowledge, not revise it. |
| OVERWRITE | Current Hypothesis, Next Action | Replace on each iteration | These represent the live state of the investigation. Old values are captured in Evidence/Eliminated when they're tested. |
在每次调试调查开始时创建此文件，包含三种类型的章节及严格的修改规则：
| 章节类型 | 章节内容 | 修改规则 | 原因 |
|---|---|---|---|
| 不可变 | 症状、重现步骤 | 会话开始时写入，永不修改 | 这些是事实基础。如果内容改变，说明是不同的bug。中途修改会导致无法追踪原始问题。 |
| 仅追加 | 证据、已排除的假设 | 添加新条目，永不删除或编辑现有条目 | 删除条目会导致未来会话重新调查已排除的方向。目的是积累知识，而非修改。 |
| 可覆盖 | 当前假设、下一步操作 | 每次迭代时替换 | 这些代表调查的实时状态。旧值在测试后会被记录到证据或已排除假设中。 |
Template
模板
markdown
undefinedmarkdown
undefinedDebug Session: [Brief Description]
调试会话：[简要描述]
<!-- Created: [timestamp] -->
<!-- 创建时间：[时间戳] -->
Symptoms (IMMUTABLE — do not edit after initial capture)
症状（不可变 —— 初始记录后请勿编辑）
- [Exact error message or behavior]
- [Environment: OS, language version, dependencies]
- [How discovered: test failure, user report, monitoring alert]
- [确切的错误消息或行为]
- [环境：操作系统、语言版本、依赖项]
- [发现方式：测试失败、用户反馈、监控告警]
Reproduction Steps (IMMUTABLE — do not edit after initial capture)
重现步骤（不可变 —— 初始记录后请勿编辑）
- [Step 1]
- [Step 2]
- [Expected vs actual result]
- [步骤1]
- [步骤2]
- [预期与实际结果]
Evidence (APPEND-ONLY — add new entries, never remove or edit)
证据（仅追加 —— 添加新条目，永不删除或编辑）
- [timestamp] [observation]: [what was found and where]
- [时间戳] [观察结果]：[发现内容及位置]
Eliminated Hypotheses (APPEND-ONLY — add new entries, never remove or edit)
已排除的假设（仅追加 —— 添加新条目，永不删除或编辑）
- [timestamp] [hypothesis]: [evidence that refuted it]
- [时间戳] [假设]：[推翻该假设的证据]
Current Hypothesis (OVERWRITE — replace each iteration)
当前假设（可覆盖 —— 每次迭代替换）
Hypothesis: [specific, testable statement]
Supporting evidence: [what points to this]
Test plan: [how to confirm or refute]
假设：[具体、可测试的陈述]
支撑证据：[指向该假设的依据]
测试方案：[验证或推翻的方法]
Next Action (OVERWRITE — replace each iteration)
下一步操作（可覆盖 —— 每次迭代替换）
[Exactly what to do next — specific enough that a new session can execute it cold]
undefined[具体的下一步操作 —— 足够详细，让新会话无需前置信息即可执行]
undefinedCritical Rule: Update BEFORE Acting
关键规则：操作前更新
Update BEFORE taking any debugging action, not after. WHY: If context resets mid-action, the file shows what was about to happen and what has already been ruled out. A post-action update means a reset loses the most recent work.
.debug-session.mdThe workflow is:
- Write your hypothesis and next action to the file
- Execute the action
- Append the result to Evidence (or Eliminated Hypotheses if refuted)
- Update Current Hypothesis and Next Action for the next iteration
- Repeat
在执行任何调试操作前更新，而非之后。原因：如果在操作过程中上下文重置，文件会显示即将执行的操作和已排除的原因。操作后更新会导致重置时丢失最近的工作成果。
.debug-session.md工作流程：
- 将假设和下一步操作写入文件
- 执行操作
- 将结果追加到证据中（若假设被推翻则追加到已排除的假设中）
- 更新当前假设和下一步操作以进行下一次迭代
- 重复
Resuming From a Reset
重置后恢复会话
When starting a debug session, check for an existing :
.debug-session.md- Read the file completely
- Do NOT re-investigate anything listed in Eliminated Hypotheses
- Resume from the Current Hypothesis and Next Action
- If Next Action was partially completed, verify its state before continuing
当开始新的调试会话时，检查是否存在：
.debug-session.md- 完整读取文件
- 绝不重新调查已排除假设中列出的任何内容
- 从当前假设和下一步操作恢复
- 如果下一步操作已部分完成，在继续前验证其状态
Debug Knowledge Base
调试知识库
Resolved debug sessions create compounding value when their findings are recorded for future investigations. This protocol maintains an append-only knowledge base of resolved bugs.
已解决的调试会话在记录结果后可产生复合价值，该协议维护一个仅追加的已解决bug知识库。
File: .debug-knowledge-base.md
.debug-knowledge-base.md文件：.debug-knowledge-base.md
.debug-knowledge-base.mdAfter resolving a bug (Phase 4 VERIFY passes), append an entry:
markdown
undefined解决bug后（阶段4验证通过），追加一条记录：
markdown
undefined[Date] [Brief Description]
[日期] [简要描述]
Keywords: [comma-separated terms for matching: error messages, component names, symptom descriptions]
Symptom: [What was observed]
Root Cause: [What was actually wrong]
Resolution: [What fixed it]
Files: [Which files were involved]
undefined关键词：[用于匹配的逗号分隔术语：错误消息、组件名称、症状描述]
症状：[观察到的情况]
根本原因：[实际问题所在]
解决方案：[修复内容]
涉及文件：[相关文件]
undefinedLookup Protocol
查询协议
At the start of every new debug investigation (Phase 1: REPRODUCE), before forming any hypotheses:
- Check if exists in the project root
.debug-knowledge-base.md - If it exists, search for keyword matches against the current symptom signature (error messages, component names, behavioral descriptions)
- Matches are hypothesis candidates, not confirmed diagnoses — the same symptom can have different root causes in different contexts
- List any matches in the Evidence section of with the note: "Prior resolution found — verify applicability before assuming same root cause"
.debug-session.md
WHY this is append-only and match-based (not a lookup table): Bugs are contextual. An "undefined is not a function" error in module A may have a completely different root cause than the same error in module B. The knowledge base accelerates hypothesis formation — it does not replace the 4-phase process.
在每次新调试调查开始时（阶段1：重现），在形成任何假设前：
- 检查项目根目录是否存在
.debug-knowledge-base.md - 如果存在，搜索与当前症状特征（错误消息、组件名称、行为描述）匹配的关键词
- 匹配结果是假设候选，而非确诊——相同症状在不同上下文中可能有不同的根本原因
- 在的证据部分列出所有匹配结果，并注明：「找到历史解决方案——在假设相同根本原因前请验证适用性」
.debug-session.md
为何采用仅追加和匹配式而非查找表：bug具有上下文相关性。模块A中的「undefined is not a function」错误与模块B中的相同错误可能有完全不同的根本原因。知识库用于加速假设形成——而非替代四阶段流程。
Analysis Paralysis Guard
分析停滞防护
This skill uses the Analysis Paralysis Guard.
If 5+ consecutive Read/Grep/Glob calls occur without an Edit/Write/Bash action,
STOP and explain what you are looking for and why before proceeding.
该技能使用分析停滞防护。
如果连续5次以上调用Read/Grep/Glob而未执行Edit/Write/Bash操作，
请停止并解释你正在查找的内容及原因，然后再继续。
Debugging-Specific Addition
调试特定补充规则
- After explaining, justification for continued reading MUST be recorded in under the Current Hypothesis section — not just stated verbally. This creates an audit trail of investigation decisions that survives context resets.
.debug-session.md
- 解释后，必须将继续阅读的理由记录在的当前假设部分——而非仅口头说明。这会创建一个可在上下文重置后保留的调查决策审计跟踪。
.debug-session.md