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:

~/.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

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:

Infers base URL from project files (package.json, .env, Procfile.dev)
Prompts for confirmation or manual URL entry
Prompts for test account username
Prompts for test account password (masked input)
Prompts for auth method (form/basic/none)
Saves to .frontend-debug/config.json
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:

Detects failure (401/403, login form still visible)
Prompts: "Authentication failed. Update credentials? (y/n)"
If yes: prompts for new password (keeps username unless changed)
Saves updated credentials
Retries authentication

Manual Config Edit: You can manually edit .frontend-debug/config.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:

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

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

Gathering Evidence:

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

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

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

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

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

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

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

Linking a Session to GitHub Issue:

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

# 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

Navigate to page with issue
Take screenshot showing problem
Inspect DOM for incorrect states
Read console for errors
Apply fix and reload
Verify correct rendering

Investigating Network Failures

Navigate to trigger network request
Monitor network requests
Identify failed requests
Examine request/response details
Fix API call or error handling
Verify successful request

Testing User Workflows

Navigate through user flow
Interact with form elements
Submit actions
Verify expected outcomes
Screenshot each step
Document any failures

Analyzing Browser Errors

Reproduce error condition
Capture console errors
Identify error source in code
Apply fix
Verify error resolved
Confirm no new errors introduced

Iterative Bug Fix with Debug Loop

Start debug session with acceptance criteria
Gather evidence (screenshot, console errors)
Form hypothesis about root cause
Apply code fix based on hypothesis
Verify in browser - check acceptance criteria
If not fixed, gather new evidence and iterate
If fixed, session completes with success
If max iterations reached, escalation report generated

Debugging Rails/Hotwire Applications (rails-dev-environment)

Ensure services are running:

./bin/dev-status.sh
# Or: docker compose ps

Start E2E browser automation services:
```
docker compose --profile e2e up -d
```

Get the correct application URL:

BACKEND_PORT=$(grep BACKEND_PORT .env | cut -d= -f2)
echo "http://localhost:${BACKEND_PORT}"

Navigate to application and authenticate
Enable Stimulus debug mode (in browser console):
```
Stimulus.debug = true
```
Check Turbo Drive status:
```
Turbo.session.drive  // Should be true
```

Find all Stimulus controllers on page:

document.querySelectorAll('[data-controller]')

View Rails logs for backend errors:

./bin/dev-logs.sh backend
# Or: docker compose logs -f backend

Access Rails console for debugging:

docker compose exec backend rails console

Check email delivery (Mailpit):

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:

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

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

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

Existing .frontend-debug/config.json
.env file for BACKEND_PORT or APPLICATION_BASE_URL
backend/.env for additional configuration
Defaults to http://localhost:3000

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

Troubleshooting

Quick diagnostics:

# 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