frontend-debug - Claude MCP Skill

# 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
- **Development Environment**: For Rails projects, ensure services are running (see Rails Dev Environment section)

## 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)
- `.env` file `BACKEND_PORT` or `APPLICATION_BASE_URL` (rails-dev-environment projects)
- `package.json` scripts (dev, start, serve)
- `.env.development`, `.env.local`, `.env` files
- `Procfile.dev`
- Defaults to `http://localhost:3000`

**Rails Dev Environment Detection**:
If `bin/dev-setup.sh`, `bin/dev-start.sh`, and `bin/dev-stop.sh` exist, the project uses the `rails-dev-environment` skill. Port allocation is read from `.env` file (e.g., `BACKEND_PORT=3004`).

**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/rails-dev-environment.md

Integration guide for projects using the `rails-dev-environment` skill:
- Detection of rails-dev-environment projects
- Service profiles (e2e, tools) for browser automation
- Starting Playwright and Selenium services
- Dynamic port allocation and URL construction
- Rails console access and debugging commands
- Hotwire/Stimulus debugging techniques

### 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

### Debugging Rails/Hotwire Applications (rails-dev-environment)
1. **Ensure services are running**:
   ```bash
   ./bin/dev-status.sh
   # Or: docker compose ps
   ```
2. **Start E2E browser automation services**:
   ```bash
   docker compose --profile e2e up -d
   ```
3. **Get the correct application URL**:
   ```bash
   BACKEND_PORT=$(grep BACKEND_PORT .env | cut -d= -f2)
   echo "http://localhost:${BACKEND_PORT}"
   ```
4. **Navigate to application and authenticate**
5. **Enable Stimulus debug mode** (in browser console):
   ```javascript
   Stimulus.debug = true
   ```
6. **Check Turbo Drive status**:
   ```javascript
   Turbo.session.drive  // Should be true
   ```
7. **Find all Stimulus controllers on page**:
   ```javascript
   document.querySelectorAll('[data-controller]')
   ```
8. **View Rails logs for backend errors**:
   ```bash
   ./bin/dev-logs.sh backend
   # Or: docker compose logs -f backend
   ```
9. **Access Rails console for debugging**:
   ```bash
   docker compose exec backend rails console
   ```
10. **Check email delivery** (Mailpit):
    ```bash
    MAILPIT_WEB_PORT=$(grep MAILPIT_WEB_PORT .env | cut -d= -f2)
    open "http://localhost:${MAILPIT_WEB_PORT}"
    ```

## Rails Dev Environment Integration

Projects created with the `rails-dev-environment` skill have Docker Compose-based development environments with built-in browser automation support.

### Detecting Rails Dev Environment Projects

Check for these indicators:
```bash
# Quick detection
test -f ./bin/dev-setup.sh && \
test -f ./bin/dev-start.sh && \
test -f ./bin/dev-stop.sh && \
echo "Rails dev environment detected"
```

### Starting Browser Automation Services

The rails-dev-environment uses Docker Compose profiles:

```bash
# Start E2E testing services (Playwright + Selenium)
docker compose --profile e2e up -d

# Verify services are running
docker compose ps | grep -E "(playwright|selenium)"

# Start development tools (Dozzle log viewer + pgAdmin)
docker compose --profile tools up -d

# Start all optional services
docker compose --profile e2e --profile tools up -d
```

### Dynamic Port Discovery

Always read ports from `.env` rather than assuming defaults:

```bash
# Get application URL
BACKEND_PORT=$(grep BACKEND_PORT .env | cut -d= -f2)
echo "Rails App: http://localhost:${BACKEND_PORT:-3000}"

# Get Mailpit URL
MAILPIT_WEB_PORT=$(grep MAILPIT_WEB_PORT .env | cut -d= -f2)
echo "Mailpit: http://localhost:${MAILPIT_WEB_PORT:-8025}"

# Get Dozzle URL (log viewer)
DOZZLE_PORT=$(grep DOZZLE_PORT .env | cut -d= -f2)
echo "Dozzle: http://localhost:${DOZZLE_PORT:-9999}"
```

### Helper Commands Reference

| Command | Purpose |
|---------|---------|
| `./bin/dev-setup.sh` | Initial setup (builds, migrations, seeds) |
| `./bin/dev-start.sh` | Start all core services |
| `./bin/dev-stop.sh` | Stop all services |
| `./bin/dev-status.sh` | Check service status |
| `./bin/dev-logs.sh` | View logs (all services) |
| `./bin/dev-logs.sh backend` | View Rails logs only |
| `./bin/dev-reset.sh` | Reset environment |
| `docker compose exec backend rails console` | Rails console |
| `docker compose exec backend rails routes` | View routes |

### URL Inference for Rails Dev Environment

When inferring the base URL, the skill checks:
1. Existing `.frontend-debug/config.json`
2. `.env` file for `BACKEND_PORT` or `APPLICATION_BASE_URL`
3. `backend/.env` for additional configuration
4. Defaults to `http://localhost:3000`

For comprehensive documentation, see `references/rails-dev-environment.md`.

## 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`

**Rails Dev Environment Issues:**
- **Services not running**: Run `./bin/dev-status.sh` or `docker compose ps`
- **Wrong port**: Read `BACKEND_PORT` from `.env`, don't assume 3000
- **E2E services unavailable**: Run `docker compose --profile e2e up -d`
- **Can't connect to application**: Check `docker compose logs backend` for errors
- **Database issues**: Run `docker compose exec backend rails db:migrate`
- **Stimulus controllers not loading**: Check browser console for JS errors, verify import maps

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