debugging
GitHub提供系统化的根因调试方法论,涵盖复现、错误分析、状态检查、隔离定位及验证修复流程。特别针对Noodle基础设施故障提供诊断表,指导用户通过日志和版本对比排查问题,避免仅修复表面症状。
触发场景
安装
npx skills add poteto/noodle --skill debugging -g -y
SKILL.md
Frontmatter
{
"name": "debugging",
"description": "Systematic root-cause debugging methodology. Use for any technical problem — errors, failures, unexpected behavior, or when stuck. Triggers: \"debug\", \"fix this\", \"what's wrong\", \"investigate\"."
}
Debugging
Read [[principles/fix-root-causes]] before starting. Every debugging session follows that principle: trace to root cause, never paper over symptoms.
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.tomlvalidation (noodle startreports diagnostics), skill frontmatter parse errors - Persistent files: brain/ notes, plan files, todos — check for corruption or stale references
- Noodle state:
-
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.
Noodle-Specific Diagnostics
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 |
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.
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.
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]].
版本历史
- 82d2921 当前 2026-11-19 21:08


