Systematic Debug Skill

A methodical approach to debugging, refactoring, and fixing issues. This skill ensures thorough documentation of all attempts and systematic testing of solutions.

When to Use

Use this skill when:

•A bug or issue persists after initial fix attempts
•Complex issues that require multiple debugging iterations
•Issues that need systematic root cause analysis
•Problems that require browser testing to verify fixes

Process

1. Create Debug Tracking File

Create a file named debug/DEBUG_{issue_title}.md in the project root with the following structure:

markdown

# Debug: {Issue Title}

## Problem Statement

{Clear description of the issue, including reproduction steps}

## Expected Behavior

{What should happen}

## Actual Behavior

{What is actually happening}

## Environment

- Date: {current date}
- Relevant files: {list of files involved}
- Browser/Runtime: {if applicable}

## Key Context

### Relevant Code

{Include the most important code snippets that are central to the issue. This helps maintain context across debugging sessions.}

```typescript
// Example: The function/component where the bug occurs
// File: path/to/file.tsx (lines X-Y)
{paste the relevant code here}
```

Data Flow

{Describe how data flows through the relevant parts of the system}

•{Step 1: e.g., "User clicks agent in chat panel"}
•{Step 2: e.g., "handleSelectAgent() is called"}
•{Step 3: e.g., "Store's selectedAgentId is updated"}
•{Step 4: e.g., "WorkspaceView effect should sync tab"}

State Shape

{If relevant, include the shape of state/props involved}

typescript

// Store state relevant to this issue
{
  selectedAgentId: string | null,
  centerView: 'map' | 'workspace' | 'file',
  // ...
}

Root Cause Hypotheses

{List hypotheses in order of likelihood, with reasoning}

•{hypothesis 1} - {why you think this might be the cause}
•{hypothesis 2} - {why you think this might be the cause}
•{hypothesis 3} - {why you think this might be the cause}

Attempt Log

Attempt 1: {Brief description}

Hypothesis: {What you think is wrong} Changes Made:

•{file}: {change description}

Testing Method: {How you tested - browser, playwright, unit tests, etc.} Result: ❌ Failed / ✅ Success Observations: {What happened, error messages, unexpected behavior} Next Steps: {What to try next based on observations}

Attempt 2: {Brief description}

...

code


### 2. Systematic Debugging Approach

For each attempt:

1. **Form a hypothesis** - Based on code analysis and previous observations
2. **Make minimal changes** - Change only what's necessary to test the hypothesis
3. **Test thoroughly** - Use appropriate testing method:
   - **Claude in Chrome MCP tools** - For UI/interaction bugs
   - **Playwright tests** - For automated regression testing
   - **Unit tests** - For logic bugs
   - **Console logging** - For state/data flow issues
4. **Document results** - Record exactly what happened
5. **Analyze and iterate** - Use observations to refine hypothesis

### 3. Testing with Claude in Chrome

When testing UI issues:

•Use tabs_context_mcp to get current browser state
•Navigate to the relevant page
•Take a screenshot to see current state
•Perform the action that should trigger the fix
•Take another screenshot to verify the result
•Document the before/after in the debug file

code


### 4. Testing with Playwright

For automated testing:

```typescript
// Create a test file: tests/debug/{issue-name}.spec.ts
import { test, expect } from '@playwright/test';

test('debug: {issue description}', async ({ page }) => {
  // Setup
  await page.goto('http://localhost:5173');

  // Reproduce the issue
  // ...

  // Verify the fix
  await expect(/* element */).toBeVisible();
});

Run with: pnpm exec playwright test tests/debug/{issue-name}.spec.ts

5. Common Debugging Patterns

React State Issues:

•Check effect dependencies
•Look for stale closures
•Verify state update order
•Check for race conditions between effects

Event/Callback Issues:

•Verify callback is being called
•Check parameter values
•Look for event propagation issues

Async Issues:

•Check promise resolution order
•Look for missing await
•Verify error handling

Store/State Management Issues:

•Log state transitions
•Check selector memoization
•Verify action dispatch order

6. Resolution

When the issue is fixed:

•Update the debug file with the successful solution
•
Add a "## Solution" section explaining:
- •The root cause
- •Why the fix works
- •Any related issues that might need attention
•Consider if a regression test should be added
•Clean up any debug logging added during investigation

Example Debug File

markdown

# Debug: Agent Tab Selection Not Working

## Problem Statement

When clicking an agent in the chat panel while on file view, the workspace opens but the wrong agent tab is selected.

## Environment

- Date: 2026-01-20
- Relevant files: CenterStage.tsx, RightSidebar.tsx, store/index.ts
- Browser: Chrome

## Root Cause Hypotheses

1. Effect execution order - auto-select effect overrides external selection
2. Store state not propagating before component mounts
3. Race condition between setCenterView and setSelectedAgentId

---

## Attempt Log

### Attempt 1: Reorder effects

**Hypothesis**: The auto-select effect runs before the sync effect
**Changes Made**:

- CenterStage.tsx: Moved sync effect before auto-select effect

**Testing Method**: Claude in Chrome - clicked agent in chat while on file view
**Result**: ❌ Failed
**Observations**: Still selecting wrong tab. Console shows both effects running.
**Next Steps**: Add guard to auto-select effect

---

### Attempt 2: Add store selection guard

**Hypothesis**: Auto-select should respect store's selectedAgentId
**Changes Made**:

- CenterStage.tsx: Added isStoreSelectionValid() check before auto-selecting

**Testing Method**: Claude in Chrome - full test sequence
**Result**: ✅ Success
**Observations**: Correct tab selected. Store selection is now respected.

---

## Solution

**Root Cause**: When WorkspaceView mounts, the auto-select effect was running and selecting the first agent, overriding the store's selectedAgentId that was set by the chat panel click.

**Fix**: Added a guard condition that checks if the store already has a valid agent selection before auto-selecting. The auto-select now only runs when there's truly no valid selection.

**Related**: May want to add similar guards to other auto-selection logic.

Key Principles

•Never guess - Form hypotheses based on evidence
•One change at a time - Makes it clear what fixed the issue
•Always test - Don't assume a change works
•Document everything - Future debugging benefits from past attempts
•Look for patterns - Similar bugs often have similar causes