debug— agent skill

A bug is a falsified assumption. Find the assumption, falsify it deliberately, observe the divergence, narrow until one line owns the lie. No speculation, no shotgun edits, no "fix and rerun" guessing.

When to Apply / NOT

Apply: test fails and cause unclear; production stack trace; intermittent / flaky behavior; wrong output without crash; regression after known commit window; heisenbug.

NOT apply: performance regression with correct outputs; security defect; symptom obvious from one-line read; architectural confusion.

Anti-patterns

• Shotgun debugging: editing several files hoping one fixes it.
• Print-and-rerun: adding logs without a target observation.
• Premature fix: patching symptom before isolating root cause.
• Ignoring the trace: stack frames are evidence.
• Changing two variables at once: defeats falsification.
• Deleting the failing test: capturing the bug is the asset.

Hypothesis Loop (language-neutral)

1. Observe — Reproduce the failure deterministically.
2. Trace — Read the failure artifact (stack, log, core dump).
3. Hypothesize — One falsifiable claim. Rank hypotheses by likelihood.
4. Instrument — Insert minimum probe (breakpoint, structured log, assertion).
5. Run — Execute the minimal repro.
6. Confirm or refute — If refuted, demote and pick next hypothesis.
7. Narrow — Binary-search the suspect range. Use git bisect for regressions.
8. Confirm root cause — Inverse test: removing/altering the cause must restore correctness.
9. Hand off — Forward to TDD: minimal repro becomes permanent failing test.

Stack-Trace Reading

• Top frame is innermost: the failure point.
• Cause vs context: An exception's caused by chain encodes why; the stack encodes where.
• Async traces: virtual stacks drop frames between awaits — capture causal context.
• Symbol fidelity: Strip-mode binaries lose frame names. Build with debug info.
• Inlined / optimized frames: <inlined> markers signal source-line-to-instruction map is approximate.

Parallel Tooling

Use procs (not ps) for PID. Use bat -P -p -n (not cat) for trace files. Use git grep -n -C 3 'pattern' (not grep) for callsites.

Constitutional Rules

1. Reproduce before fixing.
2. One hypothesis at a time.
3. Evidence over inference.
4. Capture the bug as a test (hand to TDD).
5. Confirm with inverse.
6. Bisect for regressions.
7. No silent edits.

Reasoning approach

Before hypothesizing a fix, reason through the failure — SHORT-form KEYWORDS for trace notes, observe the symptoms, trace the execution path, break down where actual behavior diverges from expected, critically review each candidate cause, validate each hypothesis against the evidence. The root cause is the smallest explanation that accounts for all observed symptoms. For numeric calculation (timing math, bound arithmetic, off-by-N analysis), invoke fend per the baseline rule; never self-calculate. Causal reasoning and trace interpretation are in-head — they are not arithmetic.

Pre-flight Check

• Before writing a plan for a bug fix that touches multiple files
• Whenever you notice that the previous attempt to fix a bug failed