Go Breakpoint Debugging

Use scripts/debug-test.sh <package> [test-regex] from the target repo root to launch Delve against one failing package or test. If there is only a log file, start with scripts/triage-failure.sh <logfile>.

Breakpoint Strategy

1. Entry breakpoint at the failing test or top-level function.
2. Divergence breakpoint before the state starts differing from expectations.
3. Error-path breakpoint where errors are created, wrapped, or returned.
4. Concurrency breakpoint around channel operations, lock boundaries, or goroutine spawn sites when the bug smells concurrent.

Hypothesis Loop

1. State what you expect before continuing.
2. Continue to the next breakpoint.
3. Compare actual runtime state with the expectation.
4. Update the hypothesis and repeat.

Delve Checklist

• Inspect locals and arguments.
• Check the stack.
• Inspect goroutines when concurrency is involved.
• Validate one root-cause hypothesis at a time.

Exit Criteria

• Root cause is backed by runtime evidence.
• The fix is minimal and safe.
• The exact failing test passes.
• The broader fast loop passes.

Use references/delve-cheatsheet.md for the common Delve commands and a short breakpoint planning reminder.