debugging-workflow

Debugging Workflow

Use this skill when the task starts from a failure or unexplained behavior. Preserve business intent, isolate the smallest failing case, and fix the confirmed cause.

Operating Rules

• Reproduce before fixing when possible.
• Read logs, stack traces, test output, screenshots, and source-of-truth docs before changing code.
• Do not replace unusual business logic with a generic solution.
• Do not make broad refactors while the failure cause is still unknown.
• Form one hypothesis at a time and test it with the fastest reliable check.
• Keep temporary debug code local and remove it before completion.
• Add or update a regression test when practical.
• If the root cause is performance-related, switch to performance-optimization.
• If the main work becomes test strategy, switch to testing-verification.

Workflow

1. Capture The Failure

• Record the exact command, URL, input, account state, branch, environment, and error output.
• Preserve stack traces and failing assertions.
• For UI bugs, capture the target element/region screenshot first, then full page only if needed.
• For user screenshots that are ambiguous, annotate unclear regions with labels and ask before coding.

2. Read Source Of Truth

• Read AGENTS.md, CLAUDE.md, relevant docs, feature specs, design-system docs, route/API/schema files, and nearby tests.
• Identify whether current behavior is wrong or the expectation is unclear.
• If docs and code disagree, call out the conflict instead of silently choosing one.

3. Reproduce And Minimize

• Run the smallest command or flow that exposes the failure.
• Reduce the input, state, fixture, route, component, or test to the smallest failing case.
• Keep reproduction steps repeatable.

4. Isolate

• Trace the failure from symptom to boundary: UI event, API request, controller, service, database, queue, cache, external dependency, build step, or deployment config.
• Inspect recent changes only as a clue, not proof.
• Use logs, debugger output, targeted prints, breakpoints, or temporary instrumentation carefully.
• Use Binary Debug only when normal reproduction and fast checks do not isolate the cause.

Read references/debugging-playbook.md for deeper isolation patterns.

5. Fix The Confirmed Cause

• Make the smallest change that fixes the confirmed cause.
• Preserve public APIs and documented behavior unless changing them is the task.
• Keep unrelated cleanup separate.
• Remove temporary debug code.

6. Prove And Document

• Rerun the failing check first.
• Run related targeted tests.
• Run broader checks when practical.
• Add or update a regression test when possible.
• Document difficult bugs in feature docs or project memory when the project would benefit.

Reporting

Report:

• Reproduction steps or why reproduction was not possible.
• Root cause.
• Files changed.
• Tests/checks/screenshots run.
• Any remaining uncertainty or skipped verification.

References

• references/debugging-playbook.md: reproduction, isolation, Binary Debug, logs, UI bugs, backend bugs, and flaky failures.