debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Debugging

调试

Read [[principles/fix-root-causes]] before starting. Every debugging session follows that principle: trace to root cause, never paper over symptoms.

开始前请阅读[[principles/fix-root-causes]]。所有调试流程都遵循该原则：追溯到根本原因，绝不要掩盖问题表象。

Process

流程

Reproduce. Get the exact error. Run the failing command, read the full output. If you can't reproduce, you can't verify your fix.
Read the error. The error message, stack trace, and line numbers are data. Read all of it before forming hypotheses. Most bugs tell you exactly where they are.
Suspect state before code. Before debugging code, check persistent state — especially on restart bugs or environment drift. See [[principles/fix-root-causes]].
- Noodle state:
```
.noodle/orders.json
```
  (stale items?),
```
.noodle/sessions/
```
  (orphaned?),
```
.noodle.toml
```
  (valid?)
- Environment: tmux sessions (
```
tmux ls
```
  ), lock files, cached artifacts
- Config:
```
.noodle.toml
```
  validation (
```
noodle start
```
  reports diagnostics), skill frontmatter parse errors
- Persistent files: brain/ notes, plan files, todos — check for corruption or stale references
Isolate. Narrow the scope. Which file? Which function? Which line? Use binary search: comment out half, see if it still fails, repeat.
Find root cause. The first "fix" that comes to mind is usually a symptom fix. Ask "why?" until you hit the actual cause:
- Test fails → mock is wrong → interface changed → type doesn't match runtime shape → fix the type
- Build fails → import error → circular dependency → restructure the modules
- Runtime crash → undefined value → missing null check → data source returns null on empty → handle empty case at the source
Fix and verify. Fix the root cause, not the symptom. Then verify: run the test, run the build, exercise the feature path. "It compiles" is not verification.
Check for the pattern. If the bug existed in one place, grep for the same pattern elsewhere. Fix all instances, or make it structurally impossible.

复现问题。 获取准确的错误信息，运行报错的命令，读取完整输出。如果你无法复现问题，就无法验证你的修复方案是否有效。
阅读错误信息。 错误消息、栈追踪、行号都是有效数据。在形成假设前先完整阅读所有内容，大多数Bug都会明确告诉你它们出在哪里。
先排查状态，再调试代码。 在调试代码前，先检查持久化状态——尤其是重启引发的Bug或者环境漂移问题。参考[[principles/fix-root-causes]]。
- Noodle 状态:
```
.noodle/orders.json
```
  (是否有过期项?),
```
.noodle/sessions/
```
  (是否存在孤立会话?),
```
.noodle.toml
```
  (是否有效?)
- 环境: tmux 会话 (
```
tmux ls
```
  ), 锁文件, 缓存产物
- 配置:
```
.noodle.toml
```
  校验 (
```
noodle start
```
  会输出诊断信息), skill 前置元数据解析错误
- 持久化文件: brain/ 笔记、计划文件、待办事项——检查是否损坏或者存在过期引用
隔离问题。 缩小排查范围：是哪个文件？哪个函数？哪行代码？使用二分法：注释掉一半代码，看是否仍然报错，重复该操作。
定位根本原因。 你想到的第一个“修复方案”通常只是修复了表象。多问几个“为什么”，直到找到真正的原因：
- 测试失败 → mock 数据错误 → 接口变更 → 类型与运行时结构不匹配 → 修复类型定义
- 构建失败 → 导入错误 → 循环依赖 → 重构模块结构
- 运行时崩溃 → undefined 值 → 缺少空值校验 → 数据源为空时返回 null → 在数据源层面处理空值场景
修复并验证。 修复根本原因，而不是问题表象。之后进行验证：运行测试、执行构建、走完功能全路径。“能编译通过”不代表验证通过。
检查同类模式。 如果某一处存在这个Bug，就全局搜索其他地方是否有相同的代码模式。修复所有实例，或者从结构上避免这类问题再次发生。

Noodle-Specific Diagnostics

Noodle 专属诊断

When debugging Noodle infrastructure failures:

Symptom	Check first
Cook won't start	`tmux ls` , `.noodle/orders.json` validity, skill resolver paths
Orders stuck	`.noodle/orders.json` for stale items, `.noodle.toml` adapter config
Missing skill	`.noodle.toml` `[skills]` paths, `.agents/skills/<name>/SKILL.md` exists
Stale mise	`.noodle/mise.json` `generated_at` timestamp, backlog sync script
Session orphaned	`.noodle/sessions/<id>/meta.json` status, `tmux ls` for zombie sessions

调试Noodle基础设施故障时：

症状	优先排查项
Cook 无法启动	`tmux ls` , `.noodle/orders.json` 有效性, skill 解析器路径
订单卡住	`.noodle/orders.json` 是否存在过期项, `.noodle.toml` 适配器配置
找不到 skill	`.noodle.toml` `[skills]` 路径配置, `.agents/skills/<name>/SKILL.md` 是否存在
mise 数据过期	`.noodle/mise.json` `generated_at` 时间戳, 待办同步脚本
会话孤立	`.noodle/sessions/<id>/meta.json` 状态, `tmux ls` 检查僵尸会话

When Stuck

思路卡壳时

Instrument, don't guess. Add logging at key points to see actual values. Read actual state ([[principles/prove-it-works]]).
Diff what changed.
```
git diff
```
,
```
git log
```
,
```
git bisect
```
. Most bugs are recent.
Simplify. Strip the failing case to minimum reproduction. Remove everything unrelated.
Change one thing at a time. Multiple changes at once make it impossible to know what fixed (or broke) it.
Check assumptions. The bug is often in the part you're sure is correct. Verify everything.

多埋点排查，不要瞎猜。 在关键位置添加日志来查看实际值，读取真实状态（参考[[principles/prove-it-works]]）。
比对变更内容。
```
git diff
```
、
```
git log
```
、
```
git bisect
```
，大多数Bug都是近期变更导致的。
简化问题。 将报错场景精简到最小可复现版本，移除所有不相关内容。
一次只改一项内容。 同时修改多处会让你无法定位到底是什么修复（或引发）了问题。
检查假设。 Bug通常出现在你确信完全正确的部分，验证所有内容。

Anti-Patterns

反模式

Bypass flags (
```
--no-verify
```
,
```
--force
```
,
```
SKIP_CHECK=true
```
) silence symptoms without fixing causes.
Retry loops hide intermittent bugs behind probability.
Shotgun debugging — changing three things to "see if it helps" — obscures causality.
Adding guards (
```
if (x !== undefined)
```
) without asking why x is undefined.

绕过校验的标志（
```
--no-verify
```
、
```
--force
```
、
```
SKIP_CHECK=true
```
）只会掩盖表象，不会修复根本原因。
重试循环会利用概率隐藏间歇性Bug。
散弹式调试——同时改三处内容来“看看有没有用”——会破坏因果关系。
不深究x为什么是undefined就直接添加守卫判断（比如
```
if (x !== undefined)
```
）。

After Fixing

修复完成后

If this bug could recur or affected your understanding, capture the lesson. Write a brain note, update a skill, or add a todo. The system should get smarter from every bug. See [[principles/encode-lessons-in-structure]].

如果这个Bug可能复发或者刷新了你的认知，记录下经验教训。写一份脑图笔记、更新技能文档，或者添加待办事项。这套系统应该从每个Bug中变得更完善。参考[[principles/encode-lessons-in-structure]]。