* test(#1961): add failing-first bug-taxonomy routing contract tests Epic #1957 Phase 2B. Source-text-is-the-product contract tests (3 taxonomy classes, explicit class->technique routing table, Bohrbug->repro+SBFL+bisect, Heisenbug->record-replay/stability+SKIP-SBFL, Concurrency->atomicity/order/ deadlock checklist, bug_class in DEBUG Current Focus, supersede-not-append) plus a routing-table specification object pinning the documented decisions (SBFL forbidden on Heisenbug is the load-bearing 1B/2B seam). Failing-first: reference, Phase 1.75, and routing-table reframe do not yet exist. * feat(#1961): add bug-taxonomy classification + strategy routing to gsd-debugger Epic #1957 Phase 2B (reliability-critical). Adds Phase 1.75: classify the failure as Bohrbug / Heisenbug-Mandelbug / Concurrency, then route the investigation technique via an explicit class->technique table (Kernighan: no opaque heuristic). Bohrbug -> reproduction + SBFL (Phase 1.25) + git bisect; Heisenbug/Mandelbug -> record-replay (rr) + stability-stress + statistical sampling, with SBFL explicitly SKIPPED (a flaky spectrum poisons the Ochiai ranking — the load-bearing 1B/2B seam); Concurrency -> the atomicity/order/deadlock checklist first. Reframes (supersedes, not appends — Zawinski) the flat 'Technique Selection by situation' table into a class-routed table; the 11 techniques remain as routed targets. bug_class recorded in Current Focus (DEBUG template); common-bug- patterns catalog cross-referenced to the taxonomy. Full rules extracted to gsd-core/references/debugger-bug-taxonomy.md. INVENTORY + manifest + agent-size baseline + install-parity goldens + AGENTS.md updated. * fix(#1961): address orthogonal review (phase-name drift, General lane, revoke framing, row-scoped tests, bounding) - HIGH: reference said 'Phase 1B' (epic shorthand); corrected to the deployed 'Phase 1.25' (matches the agent + SBFL reference). - HIGH: 6 of 11 techniques (Rubber duck, Delta, Working backwards, Differential, Comment-out, Follow-the-indirection) were orphaned by the situation-table reframe. Added a 'General (any class, situation-cued)' lane to BOTH the reference routing table and the agent's Technique Selection table that re-homes them — supersede-not-append now holds. - MEDIUM: the SBFL-skip is structurally retroactive (Phase 1.25 runs before Phase 1.75 classification), so reframed the table column from 'Do NOT use' to 'Revoke if already run' + an explicit 'retroactive revocation, not proactive skip' note stating the ordering honestly. - MEDIUM: contract tests are now row-scoped (parse the table by class, assert per-row) instead of presence-only; added a guard that the previously- orphaned techniques now have a General-lane route. - LOW: pinned the canonical bug_class value form (lowercase-kebab: bohrbug|heisenbug-mandelbug|concurrency; prose may use title-case). - NIT: added a 'Bound the Heisenbug-chase runs' note (rr/stability/sampling timeouts) per the unbounded-subprocess gauntlet. * chore(#1961): backfill changeset pr number (PR #2407)
This commit is contained in:
@@ -448,18 +448,21 @@ MISMATCH: Checker looks in wrong directory → hooks "not found" → reported as
|
||||
|
||||
**The discipline:** Never assume a constructed path is correct. Resolve it to its actual value and verify the other side agrees. When two systems share a resource (file, directory, key), trace the full path in both.
|
||||
|
||||
## Technique Selection
|
||||
## Technique Selection (routed by bug class)
|
||||
|
||||
| Situation | Technique |
|
||||
|-----------|-----------|
|
||||
| Large codebase, many files | Binary search |
|
||||
| Confused about what's happening | Rubber duck, Observability first |
|
||||
| Complex system, many interactions | Minimal reproduction |
|
||||
| Know the desired output | Working backwards |
|
||||
| Used to work, now doesn't | Differential debugging, Git bisect |
|
||||
| Many possible causes | Comment out everything, Binary search |
|
||||
| Paths, URLs, keys constructed from variables | Follow the indirection |
|
||||
| Always | Observability first (before making changes) |
|
||||
Classify the failure first (Phase 1.75), then route by class — not by ad-hoc
|
||||
situation:
|
||||
|
||||
@~/.claude/gsd-core/references/debugger-bug-taxonomy.md
|
||||
|
||||
| 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 | SBFL — Phase 1.25 runs before classification; if it ran, mark its Evidence entry revoked (flaky spectrum poisons the ranking) |
|
||||
| Concurrency | atomicity / order / deadlock checklist (see reference) FIRST | — |
|
||||
| General (any class) | Binary search, Working backwards, Differential, Delta debugging, Comment-out-everything, Follow-the-indirection, Rubber duck, Observability first (always, before changes) | — |
|
||||
|
||||
The class rows pick the first move; the General lane holds situation-cued techniques that apply to any class. When the situation table and the class route disagree, the class route wins.
|
||||
|
||||
## Combining Techniques
|
||||
|
||||
@@ -1001,6 +1004,13 @@ At investigation decision points, apply structured reasoning:
|
||||
- Any matching patterns become hypothesis candidates for Phase 2
|
||||
- If no patterns match, proceed to open-ended hypothesis formation
|
||||
|
||||
**Phase 1.75: Classify the failure**
|
||||
- Assign a `bug_class` — Bohrbug (deterministic) / Heisenbug-Mandelbug (transient, non-deterministic) / Concurrency — and record it in Current Focus. The class routes which investigation technique to use:
|
||||
|
||||
@~/.claude/gsd-core/references/debugger-bug-taxonomy.md
|
||||
|
||||
- Bohrbug → reproduction + SBFL + bisect; Heisenbug/Mandelbug → record-replay/stability (skip SBFL — flaky spectra poison it); Concurrency → the atomicity/order/deadlock checklist first
|
||||
|
||||
**Phase 2: Form hypothesis**
|
||||
- Based on evidence AND common pattern matches, form SPECIFIC, FALSIFIABLE hypothesis
|
||||
- **Branch, don't chain** — at hypothesis formation (so it's done before the Phase 4 commit), enumerate candidate causes across ≥2 Ishikawa categories (code / config / environment / data) and answer the AND-gate check; `root_cause` may hold a set when the AND-gate fires:
|
||||
|
||||
Reference in New Issue
Block a user