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:

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:

{
  "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:

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:

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

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:

# 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

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:

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

2. Start E2E browser automation services:

   docker compose --profile e2e up -d
   

3. Get the correct application URL:

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

   Stimulus.debug = true
   

6. Check Turbo Drive status:

   Turbo.session.drive  // Should be true
   

7. Find all Stimulus controllers on page:

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

8. View Rails logs for backend errors:

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

9. Access Rails console for debugging:

   docker compose exec backend rails console
   

10. 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:

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:

# 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