Debug

Debug Workflow Skill

This skill implements a systematic debug loop with runtime logs access, modeled after Cursor's Debug Mode.

Core Principle: Evidence-Based Debugging

DO NOT immediately write a fix. Like Cursor, this workflow requires:

1. Generate hypotheses first
2. Instrument code to collect runtime data
3. Fix based on actual evidence
4. Verify the fix works
5. Clean up all instrumentation

Task Classification

Before starting any work, classify the request:

Level 1: Minor Tweak (No debug loop, no commit)

Examples: Font size change, color adjustment, padding/margin tweak, text update Criteria:

• Single property change in CSS or config
• No logic changes
• Purely visual/cosmetic
• User says "just", "quick", "small", "tweak"

Action: Make the change, brief confirmation, done. No debug loop, no commit.

---
**Minor Tweak**
Changed [what] from [old] to [new] in [file]
---

Level 2: Small Change (Quick verify, no commit unless requested)

Examples: Add a CSS class, rename a variable, adjust a threshold, fix a typo in logic Criteria:

• Few lines of code
• Low risk of breaking anything
• Related to current work (part of previous task)

Action: Make change, quick browser check for errors, report. No full debug loop.

---
**Small Change**
Updated [what] in [file]
Verified: No console errors
---

Level 3: Task (Full debug loop if issues, commit when done)

Examples: New feature, bug fix, refactor, behavior change Criteria:

• Multiple files or significant logic
• Could break existing functionality
• User explicitly asks to debug/fix
• Errors are present

Action: Full debug workflow with instrumentation, verification, cleanup, and commit.

Classification Rules

• Default to lower level when uncertain
• Escalate if errors appear during quick verify
• User can override: "just make the change" = Level 1, "debug this" = Level 3
• Accumulate Level 1/2 changes; commit as batch when user says "commit" or at end of session

When Full Debug Loop Activates

• User reports a bug or error
• Code changes need browser verification AND errors are found
• Console errors or unexpected behavior observed
• User explicitly asks to "debug", "fix", "troubleshoot", or "find the bug"
• A Level 2 change reveals unexpected errors

The Debug Loop

Phase 1: Hypothesize

Before ANY code changes, generate 2-3 hypotheses:

Output format:

---
**Debug Session Started**

**Reported Issue:** [user's description]

**Hypotheses:**
1. [Most likely cause] - [why this might be it]
2. [Alternative cause] - [why this might be it]
3. [Edge case] - [why this might be it]

**Investigation Plan:** [which hypothesis to test first, what logs needed]
---

Phase 2: Instrument for Runtime Logs

This is the key step that matches Cursor's approach.

Add logging to collect: variable states, execution paths, timing information.

Method 1: Source Code Instrumentation (Primary - like Cursor)

Edit the actual source files to add debug logging:

// BEFORE
function processData(data) {
  const result = transform(data);
  return result;
}

// AFTER (instrumented)
function processData(data) {
  console.log('[DEBUG:processData] input:', JSON.stringify(data));
  console.log('[DEBUG:processData] timestamp:', Date.now());
  const result = transform(data);
  console.log('[DEBUG:processData] output:', JSON.stringify(result));
  return result;
}

Instrumentation rules:

• Prefix ALL debug logs with [DEBUG:functionName]
• Log function inputs AND outputs
• Log timestamps for async operations
• Log variable states at decision points
• Track the instrumented files for cleanup

Method 2: Runtime Injection (Supplementary)

For quick checks without modifying source, use browser injection:

mcp__chrome__evaluate_script({
  function: `() => {
    // Wrap a function to trace calls
    const original = window.someFunction;
    window.someFunction = function(...args) {
      console.log('[DEBUG:runtime] someFunction called:', args);
      const result = original.apply(this, args);
      console.log('[DEBUG:runtime] someFunction returned:', result);
      return result;
    };
    return 'Instrumentation installed';
  }`
})

Phase 3: Reproduce & Collect Logs

1. Reload the extension (if source was modified):

   • Navigate to chrome://extensions
   • Click reload button

2. Ask user to reproduce:

   ---
   **Action Required:** Please reproduce the issue by [specific steps].
   I've added instrumentation to collect runtime data.
   ---
   

3. Collect the runtime logs:

   mcp__chrome__list_console_messages({ types: ["log", "error", "warn"] })
   

4. Parse the evidence:

   • Filter for [DEBUG: prefixed messages
   • Extract variable states, execution paths, timing
   • Identify where behavior diverges from expected

Output format:

---
**Runtime Logs Collected**

**Execution Path:** [what functions were called in what order]
**Variable States:** [key values observed]
**Timing:** [any delays or race conditions]
**Anomaly Found:** [where things went wrong]
---

Phase 4: Fix Based on Evidence

Now—and only now—implement the fix:

1. Identify root cause from the collected logs
2. Implement minimal fix - target 2-3 lines when possible
3. Keep instrumentation in place for verification

Output format:

---
**Debug Loop [#]**
- Evidence: [what the logs showed]
- Root Cause: [identified problem]
- Fix: [description of change]
- Next: Verifying the fix
---

Phase 5: Verify

1. Reload extension (if modified)

2. Ask user to reproduce again:

   ---
   **Verification Required:** Please try to reproduce the bug again.
   The fix is in place. If the bug is gone, I'll clean up the debug code.
   ---
   

3. Check logs for success:

   • No errors in console
   • Expected execution path
   • Correct variable states

4. Evaluate:

   • Fixed: Proceed to cleanup
   • Not fixed: Return to Phase 2 with more instrumentation

Phase 6: Cleanup

Critical: Remove ALL instrumentation.

1. Remove all [DEBUG: logging statements from source files
2. Revert any runtime injection (page reload clears these)
3. Verify only the minimal fix remains
4. Final reload and test to confirm clean state

Output format:

---
**Debug Complete**

- Issue: [original problem]
- Cause: [root cause identified via runtime logs]
- Fix: [what was changed - should be minimal]
- Verified: [how it was tested]
- Cleanup: [instrumentation removed from X files]
---

Phase 7: Commit (After User Verification)

When the user confirms the fix is complete, automatically commit the changes:

1. Stage the fixed files (only the files with actual fixes, not any leftover debug code)

2. Create a commit with a descriptive message:

   git commit -m "Fix: [brief description of the bug fix]
   
   - Root cause: [what was wrong]
   - Solution: [what was changed]
   
   Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
   

3. Report the commit:

   ---
   **Committed**
   - Hash: [commit hash]
   - Files: [list of committed files]
   - Message: [commit message summary]
   ---
   

Note: Only commit after user explicitly confirms the fix works. Do not commit automatically after verification—wait for user confirmation.

Iteration Rules

• Max iterations: 5 before escalating to user
• Progress reports: After each iteration, output status (don't pause)
• Track instrumented files: Maintain a list for cleanup
• Escalate when:
  • Same error after 3 different fix attempts
  • Need credentials or external access
  • Multiple valid approaches require user decision
  • Issue is outside the codebase

Instrumentation Tracking

Maintain a mental list of instrumented code:

**Instrumented Files:**
- extension/modules/capacity-view.js (lines 45, 67, 89)
- extension/background.js (lines 120, 145)

This ensures complete cleanup.

Screenshot Policy

Do NOT take screenshots unless the issue can ONLY be verified visually (layout bugs, visual rendering issues, CSS problems).

For all other cases, use:

• Console logs (mcp__chrome__list_console_messages)
• Network requests (mcp__chrome__list_network_requests)
• DOM snapshots (mcp__chrome__take_snapshot)
• Script evaluation (mcp__chrome__evaluate_script)

The user can see the browser directly—screenshots waste context and add no value for functional issues.

References

• references/instrumentation.md - Detailed instrumentation patterns
• references/browser-tools.md - Chrome MCP tool reference
• references/strategies.md - Common debugging strategies