Diagnosing Bugs

A discipline for hard bugs. Skip a phase only when you can say why.

The whole skill is Phase 1: get a loop that goes red on this bug. Everything after is mechanical once you have it. If you catch yourself reading code to form a theory before that loop exists, stop — jumping to a hypothesis without a red-capable loop is the exact failure this prevents.

For trivial bugs with an obvious fix and an obvious test, skip this and just write the failing test — this skill is for the bugs that resist.

Phase 1 — Build a feedback loop

A tight loop is fast, deterministic, and goes red on this bug. Build one and the bug is 90% solved; bisection, hypothesis-testing, and instrumentation all just consume it. Be aggressive and creative here — spend disproportionate effort.

Ways to construct one — try roughly in this order

1. Failing test at the seam — dart test path/to/test.dart or flutter test, unit or widget, at whatever seam reaches the bug. Tightest loop there is.
2. fakeAsync harness — for timer, microtask, and timing-dependent bugs (most flakes). Pin the clock via options.clock, elapse time deterministically.
3. testWidgets harness — for Flutter UI bugs: pump the widget tree, drive the gesture, assert on the tree (e.g. a hit-test or navigation regression).
4. Integration test — flutter test integration_test/... when the bug crosses the native (JNI/FFI) boundary, which cannot be faked (see packages/flutter/AGENTS.md).
5. Replay a captured payload — save a real envelope / event / span / network payload to disk and replay it through the code path in isolation.
6. Throwaway harness — a minimal void main() that exercises the bug path with one call and mocked deps.
7. Stress/repetition loop — for non-deterministic bugs: run the trigger 100×, parallelise, narrow timing windows, inject delays. The goal is a higher reproduction rate, not a clean repro.
8. Differential loop — run the same input through two versions or two configs (e.g. before/after a dependency bump) and diff the output. For regressions that "appeared after X".
9. Bisection harness — if it appeared between two commits, script the red/green check and git bisect run it.

Tighten the loop

Once you have a loop, treat it as a product and tighten it:

• Faster — narrow the test scope, skip unrelated init.
• Sharper — assert the exact symptom the user described, not "didn't crash".
• More deterministic — pin the clock (options.clock), use fakeAsync, seed any randomness, avoid real network/filesystem (per test-guidelines). A 2-second deterministic loop beats a 30-second flaky one.

For non-deterministic bugs the goal is a high enough reproduction rate to debug against — a 50% flake is debuggable, 1% is not. Keep raising the rate.

Completion criterion

Phase 1 is done when you can name one command — a test invocation or script path — that you have already run at least once (paste the invocation and its output), and that is:

• Red-capable — drives the actual bug path and asserts the user's exact symptom, so it goes red now and green once fixed
• Deterministic — same verdict every run (flaky bugs: a pinned, high reproduction rate)
• Fast — seconds, not minutes

No red-capable command, no Phase 2.

When you genuinely cannot build a loop

Say so explicitly, list what you tried, and ask the user for: access to an environment that reproduces it, a captured artifact (envelope dump, log, CI run, screen recording with timestamps), or permission for temporary instrumentation. Do not hypothesise without a loop.

Phase 2 — Reproduce and minimise

Run the loop, watch it go red. Confirm it produces the failure mode the user described — not a nearby one (wrong bug = wrong fix). Then shrink the repro to the smallest scenario that still goes red: cut inputs, callers, config, and steps one at a time, re-running after each cut. Done when every remaining element is load-bearing — removing any one turns it green. The minimal repro shrinks the hypothesis space and becomes the regression test.