Debug Plan

Debug Plan Skill

ROOT AGENT ONLY - Runs only from root Claude Code agent, initiates debug workflow.

Purpose: Parse user request and create test plan for browser debugging Trigger: Phase 1 of /debug command workflow Input: User prompt describing what to debug Output: Confirmed URL + test plan with specific steps

Workflow

1. Parse prompt for URL/target

• Extract target URL from prompt:
  • Explicit URLs: http://localhost:5173/login, https://example.com/checkout
  • Implicit paths: /login, /settings, /users
  • Named targets: "the login form", "settings page", "modal on users page"
• Identify environment:
  • localhost:* → local dev server
  • *.local, 127.0.0.1 → local environment
  • Production URLs → external site
• Default port: 5173 (Vite) if not specified

2. Identify what to test

Analyze prompt for interaction types:

3. HITL: Confirm target + test plan

Present concise plan to user:

Debug Plan:
  Target: http://localhost:5173/login
  Test: Login form with test credentials
  Steps:
    1. Navigate to /login
    2. Fill email field with test@test.com
    3. Fill password field with password123
    4. Click submit button
    5. Verify redirect to /dashboard
    6. Capture console errors

Proceed? (y/n)

4. Create debug steps

Based on confirmation, structure test plan:

{
  "url": "http://localhost:5173/login",
  "viewport": { "width": 1280, "height": 720 },
  "steps": [
    {
      "id": "step-1",
      "action": "navigate",
      "description": "Navigate to login page",
      "target": "http://localhost:5173/login"
    },
    {
      "id": "step-2",
      "action": "fill",
      "description": "Enter email",
      "selector": "input[type='email']",
      "value": "test@test.com"
    },
    {
      "id": "step-3",
      "action": "fill",
      "description": "Enter password",
      "selector": "input[type='password']",
      "value": "password123"
    },
    {
      "id": "step-4",
      "action": "click",
      "description": "Submit login form",
      "selector": "button[type='submit']"
    },
    {
      "id": "step-5",
      "action": "verify",
      "description": "Check redirect to dashboard",
      "expected": "url contains '/dashboard'"
    }
  ],
  "capture": {
    "screenshots": true,
    "console": true,
    "network": true
  }
}

Action Types

URL Resolution Rules

Default ports:

• Vite: 5173
• Next.js: 3000
• Create React App: 3000
• Backend APIs: 3000-8080 range

If URL is ambiguous, ALWAYS ask user for clarification.

Viewport Presets

If prompt mentions "mobile", "tablet", or specific device, set viewport accordingly.

Test Plan Patterns

Pattern 1: Form Submission

Steps:
  1. Navigate to form page
  2. Fill all required fields
  3. Click submit
  4. Verify success message or redirect
  5. Capture console for errors

Pattern 2: Visual Layout

Steps:
  1. Navigate to page
  2. Set viewport to target size
  3. Take baseline screenshot
  4. Identify visual issue (offset, overflow, etc.)
  5. Capture DOM snapshot for analysis

Pattern 3: E2E Flow

Steps:
  1. Navigate to starting page
  2. Complete step 1 (e.g., add to cart)
  3. Navigate to step 2 (e.g., checkout)
  4. Fill payment info
  5. Submit order
  6. Verify confirmation page
  7. Capture network requests

Pattern 4: Console Error Investigation

Steps:
  1. Navigate to page
  2. Perform action that triggers error
  3. Capture console messages
  4. Take DOM snapshot at error state
  5. Identify error source (component, line number)

Pattern 5: Network Monitoring

Steps:
  1. Navigate to page
  2. Trigger API call (click button, submit form)
  3. Monitor network requests
  4. Verify request payload
  5. Verify response data
  6. Capture failed requests

Output Format

JSON structure passed to chrome-devtools-testing:

{
  "url": "string",
  "viewport": { "width": number, "height": number },
  "steps": [
    {
      "id": "string",
      "action": "navigate|click|fill|hover|press|resize|scroll|wait|verify",
      "description": "string",
      "selector": "string (optional)",
      "target": "string (optional)",
      "value": "string (optional)",
      "key": "string (optional)",
      "expected": "string (optional)",
      "duration": "number (optional)"
    }
  ],
  "capture": {
    "screenshots": boolean,
    "console": boolean,
    "network": boolean
  }
}

Validation Rules

WARN if:

• No URL provided and cannot infer from prompt
• More than 15 steps (too complex, suggest breaking into multiple tests)
• No verification steps (missing success criteria)
• Selectors are too generic (button, div) - suggest more specific ones

PASS if:

• URL is valid and accessible
• Steps are clear and actionable
• Verification criteria defined
• User confirmed plan via HITL

Integration

Called by:

• /debug command (Phase 1)

Calls:

• None (planning only)

Next step: /skill chrome-devtools-testing (Phase 2 - Setup)

Examples

Example 1: Login Form Test

Input: /debug "check if the login form works"

Output:

{
  "url": "http://localhost:5173/login",
  "viewport": { "width": 1280, "height": 720 },
  "steps": [
    {
      "id": "step-1",
      "action": "navigate",
      "description": "Navigate to login page",
      "target": "http://localhost:5173/login"
    },
    {
      "id": "step-2",
      "action": "fill",
      "description": "Enter email",
      "selector": "input[type='email']",
      "value": "test@test.com"
    },
    {
      "id": "step-3",
      "action": "fill",
      "description": "Enter password",
      "selector": "input[type='password']",
      "value": "password123"
    },
    {
      "id": "step-4",
      "action": "click",
      "description": "Click login button",
      "selector": "button[type='submit']"
    },
    {
      "id": "step-5",
      "action": "verify",
      "description": "Verify redirect to dashboard",
      "expected": "url contains '/dashboard'"
    }
  ],
  "capture": {
    "screenshots": true,
    "console": true,
    "network": true
  }
}

Example 2: Mobile Layout Issue

Input: /debug "the modal isn't centered on mobile"

HITL: "Which page has the modal? (e.g., /users, /settings)"

User: "/users"

Output:

{
  "url": "http://localhost:5173/users",
  "viewport": { "width": 375, "height": 667 },
  "steps": [
    {
      "id": "step-1",
      "action": "navigate",
      "description": "Navigate to users page",
      "target": "http://localhost:5173/users"
    },
    {
      "id": "step-2",
      "action": "resize",
      "description": "Set mobile viewport",
      "width": 375,
      "height": 667
    },
    {
      "id": "step-3",
      "action": "click",
      "description": "Open modal",
      "selector": "button[data-testid='open-modal']"
    },
    {
      "id": "step-4",
      "action": "wait",
      "description": "Wait for modal animation",
      "duration": 500
    },
    {
      "id": "step-5",
      "action": "verify",
      "description": "Check modal centering",
      "expected": "modal has left offset ~0px"
    }
  ],
  "capture": {
    "screenshots": true,
    "console": true,
    "network": false
  }
}

Example 3: Console Error Investigation

Input: /debug "there's a React error on the settings page"

Output:

{
  "url": "http://localhost:5173/settings",
  "viewport": { "width": 1280, "height": 720 },
  "steps": [
    {
      "id": "step-1",
      "action": "navigate",
      "description": "Navigate to settings page",
      "target": "http://localhost:5173/settings"
    },
    {
      "id": "step-2",
      "action": "wait",
      "description": "Wait for page load",
      "duration": 1000
    },
    {
      "id": "step-3",
      "action": "click",
      "description": "Click Save button (trigger error)",
      "selector": "button[data-testid='save-settings']"
    },
    {
      "id": "step-4",
      "action": "verify",
      "description": "Capture console errors",
      "expected": "console has React error messages"
    }
  ],
  "capture": {
    "screenshots": true,
    "console": true,
    "network": false
  }
}