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]].
1---2name: debugging3description: 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".4---5
6# Debugging
7
8Read [[principles/fix-root-causes]] before starting. Every debugging session follows that principle: trace to root cause, never paper over symptoms.
9
10## Process
11
121. **Reproduce.** Get the exact error. Run the failing command, read the full output. If you can't reproduce, you can't verify your fix.
13
142. **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.
15
163. **Suspect state before code.** Before debugging code, check persistent state — especially on restart bugs or environment drift. See [[principles/fix-root-causes]].
17 - **Noodle state**: `.noodle/orders.json` (stale items?), `.noodle/sessions/` (orphaned?), `.noodle.toml` (valid?)
18 - **Environment**: tmux sessions (`tmux ls`), lock files, cached artifacts
19 - **Config**: `.noodle.toml` validation (`noodle start` reports diagnostics), skill frontmatter parse errors
20 - **Persistent files**: brain/ notes, plan files, todos — check for corruption or stale references
21
224. **Isolate.** Narrow the scope. Which file? Which function? Which line? Use binary search: comment out half, see if it still fails, repeat.
23
245. **Find root cause.** The first "fix" that comes to mind is usually a symptom fix. Ask "why?" until you hit the actual cause:
25 - Test fails → mock is wrong → interface changed → type doesn't match runtime shape → **fix the type**
26 - Build fails → import error → circular dependency → **restructure the modules**
27 - Runtime crash → undefined value → missing null check → data source returns null on empty → **handle empty case at the source**
28
296. **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.
30
317. **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.
32
33## Noodle-Specific Diagnostics
34
35When debugging Noodle infrastructure failures:
36
37| Symptom | Check first |
38|---------|-------------|
39| Cook won't start | `tmux ls`, `.noodle/orders.json` validity, skill resolver paths |
40| Orders stuck | `.noodle/orders.json` for stale items, `.noodle.toml` adapter config |
41| Missing skill | `.noodle.toml` `[skills]` paths, `.agents/skills/<name>/SKILL.md` exists |
42| Stale mise | `.noodle/mise.json` `generated_at` timestamp, backlog sync script |
43| Session orphaned | `.noodle/sessions/<id>/meta.json` status, `tmux ls` for zombie sessions |
44
45## When Stuck
46
47- **Instrument, don't guess.** Add logging at key points to see actual values. Read actual state ([[principles/prove-it-works]]).
48- **Diff what changed.** `git diff`, `git log`, `git bisect`. Most bugs are recent.
49- **Simplify.** Strip the failing case to minimum reproduction. Remove everything unrelated.
50- **Change one thing at a time.** Multiple changes at once make it impossible to know what fixed (or broke) it.
51- **Check assumptions.** The bug is often in the part you're sure is correct. Verify everything.
52
53## Anti-Patterns
54
55- **Bypass flags** (`--no-verify`, `--force`, `SKIP_CHECK=true`) silence symptoms without fixing causes.
56- **Retry loops** hide intermittent bugs behind probability.
57- **Shotgun debugging** — changing three things to "see if it helps" — obscures causality.
58- **Adding guards** (`if (x !== undefined)`) without asking why x is undefined.
59
60## After Fixing
61
62If 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]].
poteto