Superior Debugging

Turn an observed failure into a supported causal explanation, then make the smallest complete repair. Preserve the user's scope and the repository's existing architecture while distinguishing evidence from assumptions.

Define the failure precisely

Before changing code, establish:

• the observed result, expected result, and source of that expectation;
• the smallest known reproduction and whether it is deterministic;
• the affected versions, environments, inputs, users, or data states;
• the last known good state when evidence exists;
• impact, urgency, and any unsafe reproduction boundary.

Do not silently redefine expected behavior to match the implementation. If the contract is ambiguous, identify the ambiguity and use repository evidence or user direction before treating either behavior as a defect.

Follow evidence to cause

Read references/evidence-driven-diagnosis.md when the cause is uncertain, multiple hypotheses are plausible, or a regression must be narrowed through history or controlled experiments.