# frontend-debug

> Frontend debugging using browser automation with logged-in sessions, DOM inspection, console access, and network monitoring. Use when debugging UI issues, investigating browser errors, testing user workflows, or analyzing frontend behavior in authenticated contexts. Supports Claude-in-Chrome, Playwright, Chrome DevTools, and agent-browser tools.

- Author: Arlen Greer
- Repository: arlenagreer/claude_configuration_docs
- Version: 20260205225422
- Stars: 2
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/arlenagreer/claude_configuration_docs
- Web: https://mule.run/skillshub/@@arlenagreer/claude_configuration_docs~frontend-debug:20260205225422

---

---
name: frontend-debug
description: Frontend debugging using browser automation with logged-in sessions, DOM inspection, console access, and network monitoring. Use when debugging UI issues, investigating browser errors, testing user workflows, or analyzing frontend behavior in authenticated contexts. Supports Claude-in-Chrome, Playwright, Chrome DevTools, and agent-browser tools.
---

# Frontend Debug

## Overview

This skill enables comprehensive frontend debugging through browser automation with real logged-in sessions. It provides DOM inspection, console log access, network monitoring, and screenshot capture to investigate and verify fixes for UI issues, browser errors, and user workflow problems.

## Capabilities

- **Browser Automation**: Navigate and interact with web applications using real browser instances
- **DOM Inspection**: Query and analyze DOM structure and element states
- **Console Access**: Read console logs, errors, and warnings
- **Network Monitoring**: Inspect network requests, responses, and timing
- **Screenshot Capture**: Document visual states and regression evidence
- **Session Persistence**: Work with logged-in sessions and authenticated contexts
- **Iterative Debug Loop**: Automated hypothesis-test-verify cycle with max iteration limit
- **Hypothesis Tracking**: Record and deduplicate tested approaches
- **Human Escalation**: Structured handoff when automated debugging exhausts options
- **Evidence Collection**: Gather comprehensive debugging evidence for reports
- **Investigation Reports**: Auto-generated markdown reports with session history, hypotheses, and evidence
- **GitHub Integration**: Automatic issue updates, progress comments, and resolution handling

## Requirements

- **Browser Tool**: One of the following (in priority order):
  - Claude-in-Chrome extension (preferred for logged-in sessions)
  - Playwright MCP (for automated testing)
  - Chrome DevTools MCP (for debugging)
  - agent-browser skill (fallback)
- **Target Site Access**: Valid credentials for sites requiring authentication
- **Acceptance Criteria**: Clear definition of expected behavior for fix verification

## Workflow

### 1. Session Setup

**Tool Detection**:
- Run detection script to identify available tools:
  ```bash
  ~/.claude/skills/frontend-debug/scripts/detect-browser-tools.sh --best
  ```
- The script checks availability in priority order:
  1. Claude-in-Chrome (preferred for logged-in sessions)
  2. Playwright MCP (for automated testing)
  3. Chrome DevTools MCP (for debugging)
  4. agent-browser (fallback)
- If preferred tool unavailable, see `references/setup-guidance.md`

**Tool Availability Status**:
- Full status: `~/.claude/skills/frontend-debug/scripts/detect-browser-tools.sh --all`
- JSON output: `~/.claude/skills/frontend-debug/scripts/detect-browser-tools.sh --json`
- When tools are unavailable:
  - Check if MCP is disabled in .mcp.json
  - Check if Docker container is running
  - Use toggle script: `~/.claude/skills/frontend-debug/scripts/toggle-mcp.sh status`

**Credential Handling**:
- First invocation: Runs setup flow automatically
  ```bash
  ruby ~/.claude/skills/frontend-debug/scripts/credential-prompter.rb
  ```
- Checks for existing credentials in `.frontend-debug/config.json`
- If missing: prompts for base URL, username, password, auth method
- URL is inferred from package.json, .env files, or Procfile.dev when possible
- Credentials stored locally with 0600 permissions (gitignored automatically)
- On auth failure: prompts to update credentials and retries

**Config File Location**: `[project]/.frontend-debug/config.json`
- Protected by .gitignore (added automatically on first setup)
- Contains: credentials, URLs, preferences
- NEVER commit this file (test credentials only)

**Session Initialization**:
- Navigate to target URL
- Authenticate if required
- Verify session is ready

### Configuration Management

**First Time Setup**:
When credentials are not found, the skill runs interactive setup:
1. Infers base URL from project files (package.json, .env, Procfile.dev)
2. Prompts for confirmation or manual URL entry
3. Prompts for test account username
4. Prompts for test account password (masked input)
5. Prompts for auth method (form/basic/none)
6. Saves to `.frontend-debug/config.json`
7. Ensures `.gitignore` protection

**URL Inference**:
The skill attempts to detect your dev server URL from:
- Existing config (highest priority)
- `package.json` scripts (dev, start, serve)
- `.env.development`, `.env.local`, `.env` files
- `Procfile.dev`
- Defaults to `http://localhost:3000`

**Auth Failure Recovery**:
If authentication fails with stored credentials:
1. Detects failure (401/403, login form still visible)
2. Prompts: "Authentication failed. Update credentials? (y/n)"
3. If yes: prompts for new password (keeps username unless changed)
4. Saves updated credentials
5. Retries authentication

**Manual Config Edit**:
You can manually edit `.frontend-debug/config.json`:
```json
{
  "version": "1.0",
  "credentials": {
    "username": "test@example.com",
    "password": "your-test-password",
    "auth_method": "form"
  },
  "urls": {
    "base_url": "http://localhost:3000",
    "login_path": "/users/sign_in"
  }
}
```

### 2. Debug Loop (Iterative Fix Cycle)

The debug loop orchestrates an automated hypothesis-test-verify cycle with structured escalation when debugging exhausts available options.

**Starting a Debug Session**:
```bash
# Initialize debug loop with acceptance criteria
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --start --criteria "Button turns green on click"

# Or from GitHub issue (extracts criteria from issue body)
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --start --issue "owner/repo#123"
```

**Loop Iteration Workflow**:
1. **Gather Evidence**: Capture current browser state (screenshot, console, network)
2. **Form Hypothesis**: Record suspected cause and proposed fix
3. **Apply Fix**: Make code changes to address hypothesis
4. **Verify Fix**: Check if acceptance criteria are now met
5. **Repeat or Complete**: Continue if not fixed, exit on success

**Gathering Evidence**:
```bash
# Captures before-fix screenshot for current iteration
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --gather

# Increments iteration counter
# Checks max iterations (default 5)
# Transitions to escalation if limit reached
```

**Hypothesis Recording**:
```bash
# Record hypothesis with description and proposed fix
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb \
  --hypothesis "Button click handler not bound to DOM element" \
  --fix '{"file": "app.js", "change": "Add addEventListener in componentDidMount"}'

# Duplicate hypotheses are rejected with reference to original
# Does NOT count duplicates toward iteration limit
```

**Fix Verification**:
```bash
# After applying code changes, verify behavior
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb \
  --verify "Button now turns green on click and success message appears"

# Captures after-fix screenshot
# Validates against acceptance criteria
# On success: completes session
# On failure: returns to gather_evidence for next iteration
```

**Check Status**:
```bash
# View current session state and hypothesis tracking
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --status

# Shows: state, iteration count, hypotheses tested, acceptance criteria
```

**Human Escalation**:
- Default max iterations: 5 (configurable via --max-iterations)
- On max iterations: Generates escalation report with all tested hypotheses
- Report includes: screenshots, console errors, suggested next steps
- Structured markdown format for handoff to human expert

**Escalation Report Format**:
```markdown
## ESCALATION REQUIRED

**Reason**: Maximum iterations (5) reached without resolution
**Session**: {session-id}
**Hypotheses Tested**: {count}

### Tested Approaches
1. {hypothesis description} - ❌ FAILED
2. {hypothesis description} - ❌ FAILED
...

### Evidence
- Screenshots: {before/after paths}

### Acceptance Criteria (Unmet)
- [ ] {criterion 1}
- [ ] {criterion 2}

### Suggested Next Steps
- Review hypotheses for patterns
- Check for deeper architectural issues
- Consider involving domain expert
```

### 3. Investigation Reports

Reports are automatically generated when a debug session completes (success or escalation).

**Report Contents:**
- Session metadata (ID, date, status)
- Acceptance criteria checklist (matched/unmatched)
- All hypotheses tested with outcomes
- Evidence file listings (screenshots)

**Report Location:**
```
.frontend-debug/sessions/{session-id}/report.md
```

**Manual Report Generation:**
```bash
# Generate report for current session
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --report

# Generate report using report-generator directly
ruby ~/.claude/skills/frontend-debug/scripts/report-generator.rb --session PATH
ruby ~/.claude/skills/frontend-debug/scripts/report-generator.rb --session PATH --stdout  # Print to console
```

### 4. GitHub Issue Integration

When a debug session is linked to a GitHub issue, the skill automatically:

1. **Progress Updates**: Comments on issue after each hypothesis is formed
2. **Resolution**: Posts resolution summary and closes issue on success
3. **Escalation**: Posts escalation notice (without closing) when max iterations reached

**Linking a Session to GitHub Issue:**
```bash
# Start session linked to issue
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --start --issue "owner/repo#123" --criteria "..."

# Or extract criteria from issue body
ruby ~/.claude/skills/frontend-debug/scripts/debug-loop.rb --start --issue "owner/repo#123"
```

**Issue Reference Formats:**
- `123` - Issue number (uses current repo from git context)
- `#123` - Issue number with hash
- `owner/repo#123` - Full repository reference
- `https://github.com/owner/repo/issues/123` - Full URL

**GitHub CLI Requirements:**
- `gh` CLI must be installed and authenticated
- Run `gh auth login` if not authenticated
- Handler gracefully degrades if gh unavailable

**Standalone GitHub Operations:**
```bash
# Fetch issue details
ruby ~/.claude/skills/frontend-debug/scripts/github-issue-handler.rb --fetch 123 --repo owner/repo

# Fetch with acceptance criteria extraction
ruby ~/.claude/skills/frontend-debug/scripts/github-issue-handler.rb --fetch 123 --criteria

# Add comment
ruby ~/.claude/skills/frontend-debug/scripts/github-issue-handler.rb --comment 123 --body "Investigation update..."

# Check gh authentication
ruby ~/.claude/skills/frontend-debug/scripts/github-issue-handler.rb --check
```

### 5. Manual Investigation (When Needed)

**Gather Evidence**:
- Take screenshots to document current state
- Inspect DOM for relevant elements
- Read console logs for errors/warnings
- Monitor network requests for failures

**Analyze Behavior**:
- Compare observed behavior against acceptance criteria
- Identify specific failure points
- Determine root cause from browser evidence

**Apply and Verify Fixes**:
- Edit source files based on analysis
- Reload page to test changes
- Take screenshot of fixed state
- Verify acceptance criteria met

## Resources

### references/browser-tool-reference.md

Detailed documentation of browser tool capabilities:
- Tool availability detection patterns
- Tool preference order (Claude-in-Chrome > Playwright > Chrome DevTools > agent-browser)
- Key capabilities and when to use each tool
- Docker MCP enablement for Playwright/Chrome DevTools
- Claude-in-Chrome troubleshooting and native messaging setup

### references/setup-guidance.md

Complete setup instructions for all browser tools:
- Claude-in-Chrome installation and troubleshooting
- Docker MCP server setup (Playwright, Chrome DevTools)
- Session restart requirements
- Verification checklist

### scripts/

Utility scripts for browser tool and configuration management:
- `detect-browser-tools.sh` - Detect available browser tools and select best option
- `toggle-mcp.sh` - Enable/disable Docker-based MCP servers
- `config-manager.rb` - Config file CRUD with gitignore protection
- `credential-prompter.rb` - Interactive credential collection
- `url-inferrer.rb` - Detect dev server URL from project files
- `ensure-gitignore.sh` - Ensure .frontend-debug/ is gitignored
- `session-manager.rb` - Debug session lifecycle management
- `hypothesis-tracker.rb` - Hypothesis recording with deduplication
- `screenshot-capturer.rb` - Before/after evidence capture
- `acceptance-criteria.rb` - Criteria collection and validation
- `debug-loop.rb` - Main debug loop orchestration
- `report-generator.rb` - Generate investigation reports from session data
- `github-issue-handler.rb` - GitHub issue operations via gh CLI

## Common Scenarios

### Debugging UI Issues
1. Navigate to page with issue
2. Take screenshot showing problem
3. Inspect DOM for incorrect states
4. Read console for errors
5. Apply fix and reload
6. Verify correct rendering

### Investigating Network Failures
1. Navigate to trigger network request
2. Monitor network requests
3. Identify failed requests
4. Examine request/response details
5. Fix API call or error handling
6. Verify successful request

### Testing User Workflows
1. Navigate through user flow
2. Interact with form elements
3. Submit actions
4. Verify expected outcomes
5. Screenshot each step
6. Document any failures

### Analyzing Browser Errors
1. Reproduce error condition
2. Capture console errors
3. Identify error source in code
4. Apply fix
5. Verify error resolved
6. Confirm no new errors introduced

### Iterative Bug Fix with Debug Loop
1. Start debug session with acceptance criteria
2. Gather evidence (screenshot, console errors)
3. Form hypothesis about root cause
4. Apply code fix based on hypothesis
5. Verify in browser - check acceptance criteria
6. If not fixed, gather new evidence and iterate
7. If fixed, session completes with success
8. If max iterations reached, escalation report generated

## Troubleshooting

Quick diagnostics:
```bash
# Check available tools
~/.claude/skills/frontend-debug/scripts/detect-browser-tools.sh --all

# Check config
ls -la .frontend-debug/config.json

# Check GitHub CLI
gh auth status
```

**Common Issues:**
- **No browser tools**: Run tool detection, follow setup-guidance.md
- **MCP enabled but not working**: Check Docker running, restart Claude Code session
- **Credentials failing**: Delete config, re-run setup
- **Acceptance criteria required**: Debug loop needs expected behavior defined
- **Duplicate hypothesis rejected**: Already tested - review status, form different hypothesis
- **Maximum iterations reached**: Review escalation report, consider human expert
- **gh CLI not authenticated**: Run `gh auth login`

For comprehensive troubleshooting, see `references/troubleshooting.md`.

## Best Practices

- **Always define acceptance criteria** before starting investigation
- **Take screenshots** at key investigation points for evidence
- **Document hypotheses** before applying fixes
- **Verify fixes thoroughly** before considering issue resolved
- **Preserve session state** by saving reports locally
- **Use logged-in sessions** (Claude-in-Chrome) for authenticated debugging
- **Check console and network** even when issue appears visual-only
- **Iterate quickly** - small changes, immediate verification