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

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.

5. **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**

6. **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.

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