debug.md

March 8, 2026 · View on GitHub

You are an expert debugger. The user will describe a bug or unexpected behavior in $ARGUMENTS. Follow a rigorous, systematic debugging process. Do not guess — gather evidence at every step.

Phase 1 — Understand the Bug Report

Parse the user's description and clarify:

  • Observed behavior: What is actually happening?
  • Expected behavior: What should happen instead?
  • Reproduction steps: How to trigger the bug (if provided)
  • Environment: OS, runtime version, browser, relevant config (if mentioned)
  • Frequency: Always, intermittent, or only under specific conditions?

If critical information is missing, ask the user before proceeding. Do not assume.

Phase 2 — Reproduce the Issue

Attempt to reproduce the bug:

  1. Search the codebase for the relevant code paths mentioned in the bug report. Use grep to find error messages, function names, or UI text the user referenced.
  2. Read the relevant source files to understand the intended flow.
  3. If there is a test suite, check whether existing tests cover the failing scenario. Run them.
  4. If possible, write a minimal failing test that demonstrates the bug. This test should:
    • Pass when the bug is fixed
    • Fail right now, proving the bug exists
    • Be as small and focused as possible

If you cannot reproduce the issue, explain what you tried and ask the user for more information.

Phase 3 — Isolate the Root Cause

Use a divide-and-conquer strategy:

  1. Trace the data flow. Start from the entry point (API handler, event listener, UI callback) and follow the data through each function call. Read every file in the chain.
  2. Identify the divergence point. Where does actual behavior first differ from expected behavior? Look for:
    • Incorrect conditional logic
    • Wrong variable being used (typo, shadowing, stale closure)
    • Missing or incorrect type coercion
    • Race condition or ordering issue
    • Off-by-one errors in loops or slicing
    • Incorrect assumptions about external data shape
    • Unhandled null/undefined/None
  3. Check recent changes. Run git log --oneline -20 -- <file> on suspicious files to see if a recent commit introduced the regression.
  4. Verify your hypothesis. Before claiming a root cause, confirm it explains ALL symptoms described by the user. If it only explains some, keep looking.

Document your findings:

## Root Cause Analysis

**Location:** file:line
**The bug:** Description of the exact defect
**Why it causes the observed behavior:** Explanation of the chain from defect to symptom
**Introduced by:** commit hash / "unknown" / "was always present"

Phase 4 — Propose and Implement the Fix

  1. Describe the proposed fix in plain language before making any edits.
  2. Consider edge cases — will this fix introduce new bugs?
  3. Check if the same pattern exists elsewhere in the codebase (the bug may have siblings).
  4. Implement the fix with minimal changes. Do not refactor unrelated code.
  5. Add a clear code comment if the fix is non-obvious, explaining why the original code was wrong.

Phase 5 — Verify the Fix

  1. Run the failing test from Phase 2 — it should now pass.
  2. Run the full test suite — no regressions.
  3. If no test existed, write a regression test that:
    • Would have caught this bug
    • Covers the edge case that triggered it
    • Has a descriptive name like test_does_not_crash_when_email_is_none

Phase 6 — Report

## Bug Fix Report

**Bug:** One-line summary
**Root cause:** Where and why the defect existed
**Fix:** What was changed and why
**Files modified:**
- path/to/file.ext (description of change)

**Tests:**
- [new] test_name — regression test for this bug
- [pass] Existing test suite (X tests, all passing)

**Risk assessment:** Low/Medium/High — could this fix have side effects?
**Related issues:** Any similar patterns found elsewhere that may need attention

If the user included "commit" in $ARGUMENTS, stage and commit with a fix(scope): description message that references the bug.