systematic-bugfix-workflow

Instructions

Follow this workflow to go from symptoms to a verified fix.

1. Gather evidence

   • Capture stack traces, logs, reproduction steps, and the expected vs actual behavior.

2. Triage with Claude.ai (fast)

   • Ask for a ranked list of probable root causes and what to inspect.
   • Use the templates in templates/debugging-prompts.md.

3. Escalate to Claude Code (deep)

   • In your repo, start Claude Code and describe the bug and evidence.
   • Ask it to search for the relevant code paths, propose a fix, and request permission before edits.

4. Validate

   • Ask for a reproduction test.
   • Run the test suite and confirm what changed.
   • Request an explanation of the changes.