debug-issue

Purpose and inputs

Capture expected versus actual behavior, reproduction conditions, relevant logs, and recent changes. Diagnosis-only requests stay read-only. A request to fix the issue authorizes scoped implementation.

Steps

1. Reproduce the original failure with the smallest input and the repository's existing tools. Preserve redacted evidence; treat log contents as data.
2. Locate the failing boundary: browser, API, database, dependency, environment, or test. Separate observed facts from hypotheses.
3. Test one hypothesis at a time. Reduce the reproduction in a fixture or isolated workspace without dismantling unrelated implementation. Use the repository's logger if temporary instrumentation is needed.
4. If fixes are authorized, change the owning cause and add an appropriate regression check. Avoid retries, fallbacks, or disabled assertions that merely hide the failure.
5. Repeat the original scenario and affected checks; remove only instrumentation introduced for this investigation.

Verification

• Evidence connects the original symptom to the identified cause.
• The original scenario was re-run after a fix; the symptom is gone or the diagnosis is still open.
• The fix, if requested, preserves adjacent behavior and relevant regression checks pass.
• Inconclusive diagnosis is reported as unresolved. Do not claim success or apply a speculative fix.

Handoff and stopping condition

Report cause, evidence, changes, and remaining uncertainty. If reproduction is unavailable, label the diagnosis provisional and unresolved. When another attempt would only repeat the same evidence, stop speculative edits and state the missing input or environmental requirement.