Debugging

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

Process

1. Reproduce. Get the exact error. Run the failing command, read the full output. If you can't reproduce, you can't verify your fix.

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

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

4. Isolate. Narrow the scope. Which file? Which function? Which line? Use binary search: comment out half, see if it still fails, repeat.