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.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.
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]].