Diagnosing Bugs

A disciplined feedback-loop methodology for diagnosing and resolving hard bugs, intermittent flakes, and performance regressions.

Core Principle

Never guess or hypothesize before establishing a fast, deterministic, automated feedback loop that reliably reproduces the red failure.

Core Invariants

1. Mandatory Red Loop Before Theory: Construct a fast, automated repro command and see it fail before formulating or testing any hypotheses.
2. Credential Redaction First: Redact all keys, authorization headers, tokens, and secrets with <REDACTED> before displaying outputs or logs.
3. Single Variable Instrumentation: Change only one variable at a time when probing hypothesis boundaries.
4. Unique Debug Tagging: Tag all temporary diagnostic logs with a unique searchable prefix (e.g. [DEBUG-trace]) for complete cleanup before commit.
5. Regression Test at Public Seam: Lock down the fix with a permanent test at a genuine architectural seam before declaring victory.

Architecture & Map of Content (MOC)

[ Build Tight Loop ] ──► [ Reproduce & Minimise ] ──► [ 3–5 Ranked Hypotheses ] ──► [ Targeted Probe ] ──► [ Fix & Regression Test ] ──► [ Clean ]

Step-by-Step Procedure (TWI)

Step 1: Construct a Tight Feedback Loop (Phase 1)

• Action: Build an automated runner (failing test, CLI fixture, curl script, or trace replay) that drives the bug path.
• Key Point: The loop must be fast (< 5s), deterministic, and assert the user's exact symptom.
• Inline Checklist:
  • Automated command exists and has been executed
  • Command goes red specifically on this bug symptom
  • Execution completes in seconds without manual intervention
• Why: Staring at code without a feedback loop leads to guessing and confirmation bias.

Step 2: Reproduce and Minimise (Phase 2)

• Action: Run the loop to confirm reproduction, then systematically remove non-essential config, data, and steps.
• Key Point: Every remaining line in the repro must be load-bearing (removing it turns the loop green).
• Why: Minimal repros shrink the hypothesis space and convert cleanly into permanent regression tests.

Step 3: Formulate Falsifiable Hypotheses (Phase 3)

• Action: Generate 3–5 ranked hypotheses stating the explicit prediction each makes.
• Key Point: Use format: "If X is the cause, then changing Y will make the symptom disappear."
• Why: Single-hypothesis debugging anchors on first impressions and wastes turns.

Step 4: Instrument and Isolate (Phase 4)

• Action: Insert tagged probes ([DEBUG-xxx]) or inspect values at key boundaries.
• Key Point: Change only one variable at a time; measure baselines before tuning performance bugs.
• Why: Changing multiple variables simultaneously confounds cause and effect.

Step 5: Fix, Verify, and Clean (Phases 5 & 6)

• Action: Write the regression test, apply the minimal fix, verify the full suite, and purge all debug instrumentation.
• Inline Checklist:
  • Regression test fails without fix and passes with fix
  • Original un-minimised repro confirmed green
  • All [DEBUG-...] tags purged from codebase
  • Root cause documented clearly in commit message

Anti-Rationalization Guardrails