Back to Details

evanflow-debug

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

EvanFlow: Debug

EvanFlow: Debug

Vocabulary

术语说明

See 
evanflow
meta-skill.
请查看
evanflow
元技能（meta-skill）。

When to Use

适用场景

  • Test failing
  • User reports unexpected behavior
  • Production error
  • Code does the wrong thing under specific conditions
  • Anything where the immediate symptom isn't the root cause
SKIP when: the cause is obvious and the fix is one line. Don't ceremonialize trivial bugs.
  • 测试失败
  • 用户反馈异常行为
  • 生产环境报错
  • 代码在特定条件下执行错误操作
  • 任何直接表现并非根本原因的情况
跳过场景： 原因明显且修复仅需一行代码的情况。无需为 trivial Bug 走流程。

The Flow

流程步骤

1. Reproduce

1. 复现问题

  • Get the exact reproduction: input, environment, steps
  • Reproduce locally if possible. If you can't reproduce, the bug is unverified — say so before proceeding.
  • 获取精确的复现信息：输入参数、环境、操作步骤
  • 尽可能在本地复现。若无法复现，则Bug未经验证——在继续前需明确说明这一点。

2. Form a Hypothesis

2. 提出假设

State the hypothesis explicitly:
"I think the bug is in <file>:<line> because when X happens, Y is supposed to happen but instead Z does."
A vague "probably the validation" is not a hypothesis.
明确陈述假设：
"我认为Bug出现在<文件>:<行>，因为当X发生时，预期应执行Y，但实际执行了Z。"
模糊的表述如“可能是验证环节有问题”不构成有效的假设。

3. Embedded Grill — Challenge the Hypothesis

3. 嵌入式质询——验证假设

Before writing any fix, ask:
  • Symptom vs. cause: "Is this where the bug manifests, or where it originates? Trace one step further upstream."
  • Coverage: "What other code paths share this root cause? Will the fix here leave those paths broken?"
  • Reversibility: "Does the fix have the same blast radius as the bug, or wider?"
  • Test gap: "Why didn't a test catch this? Is the test missing, wrong, or misaligned with real behavior?"
  • Domain check: "Is the bug actually behaving correctly per spec, and the spec is wrong?"
在编写任何修复代码前，先问自己：
  • 表现 vs 原因："这是Bug的表现位置，还是根源位置？再向上追溯一步。"
  • 覆盖范围："还有哪些代码路径存在相同的根本原因？此处的修复是否会遗漏这些路径？"
  • 可逆性："修复的影响范围是否与Bug一致，还是更广？"
  • 测试缺口："为什么测试没有发现这个问题？是测试缺失、错误，还是与实际行为不符？"
  • 领域校验："是否Bug的实际行为符合规范，而是规范本身有误？"

4. Verify the Hypothesis Before Fixing

4. 修复前验证假设

Add an instrument (log, breakpoint, test assertion) that proves the hypothesis right or wrong. Watch the instrument fire. If it doesn't, the hypothesis is wrong — go back to step 2.
添加工具（日志、断点、测试断言）来证明假设正确与否。观察工具的触发情况。若未触发，则假设错误——回到步骤2。

5. Write a Failing Test First

5. 先编写失败的测试用例

The test should fail because the bug exists. This is a vertical-slice TDD application — see 
evanflow-tdd
.
该测试用例应因Bug存在而失败。这是垂直切片TDD的应用——请查看
evanflow-tdd
。

6. Fix at the Root

6. 从根源修复

Fix where the root cause originates, not where the symptom appears. If the fix is far from the symptom, leave a comment explaining the WHY (this is one of the few cases where a code comment earns its keep).
在根本原因的源头进行修复，而非表现位置。若修复位置与表现位置相距较远，请留下注释解释原因（这是少数值得添加代码注释的场景之一）。

7. Verify the Test Passes

7. 验证测试通过

Run the test. Run the broader suite. Confirm no regressions.
运行测试用例。运行更全面的测试套件。确认无回归问题。

Hard Rules

硬性规则

  • No fix without a failing test that demonstrates the bug. (Same TDD principle as evanflow-tdd.)
  • Fix the root, not the symptom. Symptom-fixes are how bugs metastasize.
  • Never auto-commit. A fix gets staged; user confirms before commit.
  • If you can't reproduce, say so. Don't fix invisible bugs.
  • 无失败测试用例则不修复（与evanflow-tdd的TDD原则一致）。
  • 修复根源，而非表现。仅修复表现会导致Bug扩散。
  • 绝不自动提交。修复代码暂存后，需由用户确认再提交。
  • 若无法复现，明确说明。不要修复无法复现的Bug。

Hand-offs

交接流程

  • Fix complete, tests pass → if mid-plan, return to 
    evanflow-executing-plans
    . If standalone debug, report what was fixed and STOP. The user decides whether to commit or take further action.
  • Discovered an architectural issue → 
    evanflow-improve-architecture
  • Discovered the spec is wrong → 
    evanflow-brainstorming
    to align on intended behavior
  • 修复完成且测试通过 → 若处于执行计划中，返回
    evanflow-executing-plans
    。若为独立调试任务，报告修复内容后停止。由用户决定是否提交或采取进一步行动。
  • 发现架构问题 → 转入
    evanflow-improve-architecture
  • 发现规范有误 → 转入
    evanflow-brainstorming
    以对齐预期行为