Debugging Workflow

Provides: A disciplined loop for establishing cause before changing code, plus guardrails for flaky tests and production symptoms.

Quick Reference

Golden Rule: Do not fix before reproducing or collecting strong evidence

Loop: Capture → Reproduce → Bound → Hypothesize → Inspect → Fix → Verify

Bias: smallest repro, smallest change, strongest verification

Never: mask an error to make a test pass, or accept the stack trace root as the root cause

Workflow

1. Capture

Record the exact command, input, error output, relevant logs, versions, and recent changes. Preserve long output in a file and quote only the relevant lines, so the investigation stays readable and the raw evidence stays available.

2. Reproduce

Run the narrowest failing test or command that shows the problem. If it does not reproduce, keep gathering evidence rather than editing code speculatively. An intermittent failure that you cannot trigger on demand is not yet ready to fix.

Note explicitly whether the repro is reliable, intermittent, or not yet achieved.

3. Bound the fault

Establish the boundary between what works and what does not:

• What changed recently: code, config, dependencies, data, environment.
• What still works, including the nearest passing case.
• Which components sit between the input and the failure.

Compare a known-good path against the failing path. The difference is where the cause lives.

4. Hypothesize

List one to three plausible causes with the evidence for and against each. Prefer hypotheses you can falsify quickly over the ones that feel most likely, because a fast disproof narrows the space more than a slow confirmation.

5. Inspect or instrument

Read the call path and the invariants it assumes before searching broadly. Add temporary logging or assertions only to answer a specific question you have already framed. Instrumentation added without a question produces noise.

6. Fix

Make the smallest change that addresses the confirmed cause. Resist drive-by refactors in the same change: they make it harder to tell whether the fix worked and harder to revert if it did not.

7. Verify

• Add or update a regression test that fails without the fix.
• Run the original failing command.
• Run nearby coverage to check for collateral damage.
• Remove the temporary instrumentation.

Evidence Note

Keep a compact trail in the conversation or the task list. Do not create a new file for it unless asked:

Failure: {command and error}
Repro: {reliable | intermittent | not yet}
Likely cause: {cause with the evidence supporting it}
Fix: {the change}
Verification: {commands and tests run}

Guardrails

Do not assume the stack trace root is the root cause. The frame that threw is where the invariant was violated, not always where it was broken. A null dereference deep in a library usually means a caller passed something it should not have.

Do not mask errors to make tests pass. Widening a catch block, loosening an assertion, or adding a retry around a deterministic failure hides the bug and removes the signal that would catch it next time.

Do not broaden scope before the narrow path is understood. Rewriting a component because it "seems fragile" while the actual cause is unknown produces a new unknown state.

For flaky tests, separate the infrastructure cause from the product bug. The usual causes are timing assumptions, test ordering dependencies, and shared mutable state between tests. A test that fails only in CI is often revealing a real race that local timing hides.

For production issues, mitigate first and investigate second. Rollback and impact reduction come before root-cause depth. Preserve evidence, such as logs and failing payloads, before restarting anything that would clear it.

Checklist

Before finishing a debug fix:

• The original failure was reproduced, or the evidence explains why it cannot be
• The cause is supported by code, logs, tests, or a falsified alternative
• The fix is minimal and does not hide the symptom
• A regression test fails without the fix and passes with it
• The original failing command and nearby coverage pass, or gaps are stated
• Temporary logging and assertions are removed

See also

• Load standards-testing when adding regression tests or investigating flakes.
• Load standards-observability for logs, metrics, traces, and production symptoms.
• Load standards-security if the bug touches authentication, secrets, or user data.
• Load role-site-reliability-engineer for active incidents needing mitigation first.
• Load the language-specific standards skill before editing implementation code.