debug

name	debug
description	Systematic debugging skill. Use when user reports "not working", "error", "doesn't behave as expected", or after repeated fix failures. Enforces "diagnose before fix" and proactively identifies information gaps and knowledge blindspots.

Debugging Protocol

Follow steps in order. Do not skip.

Core Principles

1. Diagnose before fix - Never modify code until cause is confirmed
2. Expose uncertainty - When information is insufficient or technology unfamiliar, you MUST inform the user
3. Direction over details - Optimizing in the wrong direction is meaningless

---

Step 1: Information Assessment

Upon receiving an issue, check if you have:

• Complete error message or stack trace
• Expected behavior vs actual behavior
• Where the problem occurs (input/processing/output)
• Relevant logs
• Reproduction: Is it consistent? What are the minimal steps to reproduce?

When information is insufficient, you MUST state: What's missing, where to get it, why reliable diagnosis is currently impossible. Do NOT guess when information is lacking.

---

Step 2: Knowledge Gap Check

You MUST proactively declare and request docs/examples for:

• SDKs/APIs released after 2024
• Fast-iterating frameworks (AI SDK, Vercel AI, LLM APIs, etc.)
• Uncommon libraries or internal company APIs

Declaration format: "This involves [technology name]. My knowledge may be outdated. Please provide official docs or a working reference example."

---

Step 3: Diagnostic Analysis

NO CODE MODIFICATIONS in this step.

Output a diagnostic report containing:

1. Scope: Is this user code or a third-party library issue? Use binary search to narrow down: at which layer does it start failing?
2. Possible causes (ranked by likelihood, each with supporting evidence and confidence level)
3. Information gaps (if any)
4. Knowledge gaps (if any)
5. Verification plan (where to add logs to validate hypotheses)

---

Step 4: Add Verification Logs

After user confirms the direction, add logs to verify hypotheses.

Electron special handling:

• Main process: console.log output is directly visible
• Renderer process: Must forward via IPC to main process, or prompt user to copy from DevTools

---

Step 5: Fix After Confirmation

Before starting fixes, ALL must be satisfied:

• Root cause confirmed via logs/evidence (not guessing)
• User confirmed the diagnostic direction
• Reference obtained for unfamiliar technology

When fixing, state: confirmed cause, supporting evidence, fix approach, expected outcome.

---

Direction Check (Critical)

Trigger conditions: 2+ failed fix attempts, OR new error types appearing after fixes.

When triggered, you MUST:

1. Question the technical approach source: Is this my recommendation or based on references? Could my "common knowledge" be wrong?

2. Request reference project: Are there open source implementations of similar functionality? Can we compare their approach?

3. Challenge fundamental assumptions: Is the problem we've been solving actually in the wrong direction? (e.g., we've been fixing PATH, but maybe we shouldn't be using node at all?)

4. Question the problem itself: Is what we're solving the real problem? Or is it a symptom of a deeper issue?

Without reference projects: Explicitly suggest user search for similar open source implementations first — this is more effective than continued guessing.

---

Handling Repeated Failures

When multiple failures detected, consider in priority order:

1. Wrong direction → Execute Direction Check above
2. Information gaps → State what additional information is needed
3. Knowledge gaps → Request official docs or examples
4. Wrong localization → Re-localize using binary search