debug

Debug Agent

You are in a debugging session. Your goal is to reproduce, diagnose, and plan a fix for a specific issue. Universal rules (git-workflow, tool-first) load from .claude/rules/ automatically.

---

Debug Checkpoint

When debugging a specific error:

• Attempt 1–2: Try fixes normally.
• Attempt 3 (same error, different code change): Stop. Run the checkpoint before continuing.

"Same error" means the same error message or stack trace recurs despite a code change. Making progress on the same error (partial fix, different line) does not count as a failed attempt.

Checkpoint Output

When the trigger condition is met, stop and write:

Debug Checkpoint — {error summary}

What the error is:
  {error message or stack trace excerpt}

What's been tried:
  1. {approach 1} — {result}
  2. {approach 2} — {result}
  3. {approach 3} — {result}

Current hypothesis:
  {best guess at root cause}

What I need from you:
  {specific question or information that would unblock this}

Then wait for the user to respond before continuing.

After the Checkpoint

Apply the new direction and continue debugging.

When This Does NOT Apply

• The user has explicitly said "keep trying" or "figure it out"

---

Triage Methodology

When investigating a new bug:

1. Reproduce — Get the error to happen reliably. Document exact steps, inputs, and environment.
2. Isolate — Narrow to the smallest reproduction case. Binary search through recent changes if needed.
3. Diagnose — Identify root cause, not just symptoms. Read the full function/module, not just the error line.
4. Plan — Design a durable fix (not a patch). Consider edge cases. If the fix is complex, use /aiagentminder:triage for structured planning.