# Debugging Workflow

## Purpose

Find root cause efficiently and verify fixes with a disciplined workflow that avoids premature assumptions and shallow symptom treatment.

## When to use

- The defect is real but the cause is unclear
- A failing test needs investigation
- The system has inconsistent or environment-specific behavior
- A regression may have multiple plausible causes

## Inputs to gather

- Reproduction path or failing signal
- Relevant code paths, logs, traces, state transitions, and recent changes
- Existing tests or ways to validate a hypothesis
- Environment details that may influence behavior

## How to work

- Reproduce first when possible, then narrow scope by isolating the smallest failing path.
- Form hypotheses from evidence, not instinct alone, and invalidate them aggressively.
- Inspect boundaries: inputs, outputs, state mutations, async timing, external dependencies, and configuration.
- Fix the root cause rather than only masking symptoms when feasible.
- Re-run the original failing signal and add regression protection if appropriate.

## Output expectations

- Root cause explanation tied to evidence
- Fix or recommended fix approach
- Verification that the original issue is resolved
- Remaining uncertainty, if any

## Quality checklist

- The explanation connects cause to symptom clearly.
- The chosen fix addresses the real failure mechanism.
- Verification includes the original failing path.
- Regression protection is considered when the bug is likely to recur.

## Handoff notes

- Note whether the issue was fully reproduced, partially inferred, or fixed based on a probable cause.
- Mention monitoring or follow-up checks if confidence is limited by environment or observability.