browser-debug

What this skill does

# Browser Debug Skill

Comprehensive browser log capture for AI-led debugging using Chrome DevTools MCP.

Works with any Chromium-based browser: **Dia, Chrome, Edge, Brave, Opera, etc.**

## When to Use This Skill

This skill auto-loads when:
- Debugging browser console errors
- Investigating network request failures (API errors, CORS issues)
- Analyzing page performance issues
- Reproducing and diagnosing user-reported bugs
- Conducting systematic browser debugging sessions
- Working with web applications during development

## Browser Compatibility

**✅ Supported Browsers** (Chromium-based):
- **Dia** (primary - Chromium-based browser)
- Google Chrome
- Microsoft Edge
- Brave Browser
- Opera
- Vivaldi
- Any browser using Chrome DevTools Protocol

**Why Chromium?** These browsers all use the Chrome DevTools Protocol, which provides consistent debugging APIs across platforms.

## Log Capture Workflow

### Step 1: Initialize Session
Create timestamped session directory for organized log storage:
- Directory: `~/browser-logs/sessions/YYYYMMDD-HHMMSS-{page-description}/`
- Symlink: `~/browser-logs/latest/` points to most recent session
- Configurable via `~/.claude/forge/config/browser-capture.yaml`

### Step 2: Capture Console Logs
Use Chrome DevTools MCP to capture all console messages with filtering:

**Error messages** (critical):
```python
mcp__plugin_product-design_chrome-devtools__list_console_messages(
    pageIdx=0,
    pageSize=100,
    types=["error"],
    includePreservedMessages=True  # Last 3 navigations
)
```

**Warnings** (important):
```python
mcp__plugin_product-design_chrome-devtools__list_console_messages(
    pageIdx=0,
    pageSize=100,
    types=["warn"],
    includePreservedMessages=True
)
```

**All logs** (context):
```python
mcp__plugin_product-design_chrome-devtools__list_console_messages(
    pageIdx=0,
    pageSize=100,
    types=["error", "warn", "info", "log", "debug"],
    includePreservedMessages=True
)
```

**Output files**:
- `console-error.log` - Only errors
- `console-warn.log` - Only warnings
- `console-all.log` - All console output

### Step 3: Capture Network Activity
Capture network requests with filtering:

**Failed requests** (4xx, 5xx errors):
```python
# List all requests first
mcp__plugin_product-design_chrome-devtools__list_network_requests(
    pageIdx=0,
    pageSize=100,
    resourceTypes=["xhr", "fetch", "document"],  # Exclude static assets
    includePreservedRequests=False
)

# Then filter for failures (status >= 400)
```

**XHR/Fetch API calls**:
```python
mcp__plugin_product-design_chrome-devtools__list_network_requests(
    pageIdx=0,
    pageSize=100,
    resourceTypes=["xhr", "fetch"],
    includePreservedRequests=False
)
```

**Get detailed request data**:
```python
mcp__plugin_product-design_chrome-devtools__get_network_request(
    reqid=67890,
    responseFilePath="/path/to/session/response-67890.json",
    requestFilePath="/path/to/session/request-67890.json"
)
```

**Output files**:
- `network-errors.log` - Failed requests only
- `network-all.log` - All network activity
- `network-detail.json` - Full request/response data

### Step 4: Capture Performance (Optional)
For performance debugging, capture trace data:

```python
# Start performance tracing
mcp__plugin_product-design_chrome-devtools__performance_start_trace(
    reload=False,  # Capture current session
    autoStop=False
)

# ... perform operations ...

# Stop and save trace
mcp__plugin_product-design_chrome-devtools__performance_stop_trace(
    filePath="/path/to/session/performance-trace.json.gz"
)
```

**Output file**:
- `performance-trace.json.gz` - Chrome DevTools-compatible trace

### Step 5: Analyze and Report
Generate debugging report with findings and recommendations:

1. **Parse captured logs** - Identify error patterns, failed requests, performance issues
2. **Correlate errors** - Match console errors with network failures
3. **Provide insights** - Root cause analysis and recommendations
4. **Suggest fixes** - Code changes or configuration updates

## Quick Reference: Forge CLI Command

For automated capture, use the `forge browser-capture` command:

```bash
# Capture everything
forge browser-capture --page "Dashboard" --all

# Capture only console errors
forge browser-capture --console --errors-only

# Capture network requests (exclude static resources)
forge browser-capture --network --exclude-static

# Custom output directory
forge browser-capture --page "Login Flow" --output ./test-logs --all
```

**Command options**:
- `--page` - Page description for session naming
- `--console` - Capture console messages only
- `--network` - Capture network requests only
- `--performance` - Capture performance trace only
- `--all` - Capture all logs (default)
- `--output` - Custom output directory
- `--exclude-static` - Exclude images, fonts, stylesheets
- `--errors-only` - Only capture errors and warnings

## Integration with Existing Skills

This skill complements other Product Forge debugging skills:

### Console Debugging Skill
**When to use**: Deep analysis of console error messages
- Use `/console-debugging` after capturing logs
- Provides detailed error analysis and stack trace interpretation
- Focus on JavaScript errors, syntax issues, runtime exceptions

### Network Inspection Skill
**When to use**: Detailed network request investigation
- Use `/network-inspection` after capturing network logs
- Analyzes API calls, CORS issues, authentication failures
- Request/response header analysis

### Debug Orchestrator Skill
**When to use**: Complex multi-layer debugging across frontend/backend
- Use `/debug-orchestrator` to coordinate browser + backend debugging
- Orchestrates multiple debugging skills for end-to-end investigation
- Manages complex debugging workflows

## Configuration

**Config file**: `~/.claude/forge/config/browser-capture.yaml`

Auto-created on first run with sensible defaults:

```yaml
output_dir: ~/browser-logs

console:
  levels: [error, warn, info, log]
  include_preserved: true  # Last 3 navigations

network:
  exclude_types: [image, font, stylesheet, media]
  save_errors_separately: true
  capture_bodies: false

performance:
  enabled: false  # Enable on-demand
  duration_seconds: 10

filters:
  exclude_urls:
    - "*.map"
    - "*analytics*"
    - "*tracking*"
  exclude_console_patterns:
    - "Download the React DevTools"

output:
  create_symlink: true  # Create 'latest' symlink
  max_sessions: 50      # Future: auto-cleanup
```

**Customization**:
- Edit `~/.claude/forge/config/browser-capture.yaml`
- Command-line options override config values
- Invalid config falls back to safe defaults

## Common Debugging Patterns

### Pattern 1: Error Investigation
1. Navigate to page with error in browser
2. Reproduce error or problematic behavior
3. Capture console errors immediately:
   ```bash
   forge browser-capture --console --errors-only
   ```
4. Analyze error messages in `console-error.log`
5. Check network logs for related API failures

### Pattern 2: Network Debugging
1. Navigate to page with API issues
2. Trigger API calls (login, data fetch, etc.)
3. Capture network activity:
   ```bash
   forge browser-capture --network --exclude-static
   ```
4. Review `network-errors.log` for failed requests
5. Examine `network-detail.json` for request/response details

### Pattern 3: Performance Analysis
1. Navigate to slow-loading page
2. Start performance trace before action:
   ```bash
   forge browser-capture --page "Slow Page" --performance
   ```
3. Perform slow operation
4. Analyze trace in Chrome DevTools (load `performance-trace.json.gz`)
5. Identify bottlenecks and optimization opportunities

### Pattern 4: Comprehensive Debugging
1. Start comprehensive capture:
   ```bash
   forge browser-capture --page "Full Debug Session" --all
   ```
2. Allow AI agent to interact with page
3. Logs automatically captured in organized structure
4. Review session directory for all artifacts
5. Use other skills fo