msd-core/gsd-core/references/debugger-bug-taxonomy.md

Bug-Taxonomy Classification + Strategy Routing

Loaded by gsd-debugger via @-include from Phase 1.75 (classify the failure) and the Technique Selection table. Classifies the failure early and routes which investigation technique to use, replacing (not appending to) the flat "pick something from the menu" habit with selection-by-class.

Why this exists

The 11 investigation techniques are all still here — they are the routed targets, not an undifferentiated list. But picking the right technique ad hoc wastes cycles or actively misleads: a deterministic Bohrbug wants reproduction + fault localization + bisection; a Heisenbug/Mandelbug will disappear or change under naive repro-and-inspect and wants record-replay or stability-stress; a concurrency bug wants the atomicity/order/deadlock checklist before general techniques. Classification takes one sentence and routes the rest.

The taxonomy (Phase 1.75 — classify before forming hypotheses)

Record bug_class in Current Focus (lowercase-kebab value: bohrbug, heisenbug-mandelbug, or concurrency — prose may use title-case for readability) as one of:

• Bohrbug — solid, deterministic, always reproduces under the same inputs (named for the Bohr atom: solid, localized, easy to pin down).
• Heisenbug / Mandelbug — transient, non-deterministic, changes under observation; Mandelbug specifically covers aging-related failures (resource exhaustion, uptime-dependent state, slow accumulation) whose cause is tangled with the system rather than purely timing.
• Concurrency — atomicity-violation, order-violation, or deadlock (the Lu et al. 2008 classification) arising from interleaved execution.

If the class is genuinely unclear after one observation, gather one more piece of evidence (does it reproduce on immediate retry? does it depend on uptime?) rather than forcing a guess — but record the leading candidate as bug_class and revise it as evidence accumulates.

The routing table (explicit, inspectable — Kernighan: no opaque heuristic)

bug_class	Route to	Revoke if already run
Bohrbug	deterministic reproduction → SBFL (Phase 1.25) → git bisect → binary search	—
Heisenbug / Mandelbug	record-replay (rr) → stability-stress → statistical sampling; for Mandelbug, look for resource-exhaustion / uptime-dependent patterns	SBFL — if Phase 1.25 already ran, mark its Evidence entry revoked (flaky spectrum poisons failed(s))
Concurrency	the atomicity / order / deadlock checklist (below) FIRST, then general techniques	—
General (any class — situation-cued)	Binary search (large codebase), Working backwards (known desired output), Differential debugging (worked-before/works-elsewhere), Delta debugging (large change set), Comment out everything (many possible causes), Follow the indirection (constructed paths/URLs/keys), Rubber duck (confused), Observability first (always, before changes)	—

The class-routed rows decide which technique to reach for first. The General lane holds the situational techniques that apply regardless of class — they are not orphaned; they are the second move once the class-specific route has been exhausted or does not apply.

The SBFL rule is retroactive revocation, not proactive skip

Note the ordering: Phase 1.25 (SBFL) runs before Phase 1.75 (classification), so for a Heisenbug the SBFL-skip cannot fire proactively — it fires as retroactive revocation. When the class later resolves to Heisenbug or Mandelbug, mark the prior SBFL Evidence entry as revoked (do not delete — see debugger-sbfl.md) and note why. A flaky "failing" test makes failed(s) unreliable, so the Ochiai ranking is noise on a Heisenbug spectrum.

The concurrency checklist (suspected Concurrency class)

Run this BEFORE general techniques:

1. Atomicity — is a read-modify-write non-atomic? (check-then-act without a lock, missing compare-and-swap, a "get then set" across an await/yield)
2. Order — can two operations legally interleave to produce the bad state? (missing happens-before / synchronization; publish-before-init; init order across async boundaries)
3. Deadlock — circular wait on locks/resources? (hold-and-wait, no preemption, mutual blocking on shared resources)

If any branch hits, that becomes the leading hypothesis for Phase 2 (and feeds the RCA candidate_causes — concurrency bugs typically bridge code + environment, per debugger-rca-branching.md).

Relationship to the other disciplines

• SBFL (Phase 1.25) is the go-to pre-filter for Bohrbugs; it is explicitly not trusted on Heisenbug/Mandelbug spectra (retroactively revoked — see above).
• RCA branching (Phase 2A) still applies once the route lands you at a hypothesis — concurrency bugs almost always AND-gate (code race + environment/config amplification), so branch across categories.

Bound the Heisenbug-chase runs (CLAUDE.md gauntlet — unbounded subprocess)

rr record on a real application, stability-stress runs, and statistical sampling (N repeated executions) can each run minutes-to-hours. Bound them: cap rr record and each stress/sampling loop (60s for npm-tier, scale with suite size; a fixed iteration count for sampling), and degrade to a logged skip on timeout — never let a Heisenbug chase hang the debug session. If a run is cut short, note how far it got in Evidence.

Supersede, not append (Zawinski's Law)

This replaces the flat "Technique Selection by situation" habit with "Technique Selection by bug class." The 11 techniques remain available in <investigation_techniques> as the routed targets: the three class rows route the first move, and the General lane holds the situation-cued techniques that apply to any class. Where a class route and a situation-based hunch disagree, the class route wins (a situation table can't tell a Bohrbug from a Heisenbug; the class can).

Scope boundary

Classification + one routing table + the concurrency checklist. Not a new subsystem, not a probability model, not an auto-classifier — the agent reads the symptoms and assigns the class by judgment, then the table routes. The chosen class and strategy are written to the debug file so the decision is inspectable.