/visual-exploration

name: visual-exploration
description: Layer 1 skill for browser automation and visual UX documentation. Initial reconnaissance, navigation mapping, interaction documentation, end-to-end flow capture, edge case exploration, screenshot methodology. Loaded by the analyzer agent during Layer 1.

Visual Exploration Methodology

Document behavioral intelligence through browser automation and visual observation. Every screenshot is an empirical observation. Every interaction sequence is a behavioral flow. This mode captures what the user SEES and what the system DOES in response to user actions.

When to Use This Mode

Visual exploration activates when:

• The target is a web application with a UI
• The discovery inventory identifies a running web UI accessible via HTTP
• A running instance of the target is accessible via HTTP

This mode requires a running instance of the target application and browser automation capabilities (Playwright, Puppeteer, or equivalent). All output is **RAW** (screenshots and flow documentation capture the target's UI in detail).

Targets without a web UI get no useful signal from this mode — skip it.

Why Visual Exploration Matters

Source code tells you what the system CAN do. Tests tell you what the system MUST do. Visual exploration tells you what the system LOOKS LIKE while doing it. This is behavioral intelligence that no other mode captures:

• **Affordances** -- what actions does the UI present as available?
• **Feedback** -- how does the system communicate success, failure, and state changes?
• **Navigation structure** -- how are features organized from the user's perspective?
• **State representation** -- how does the UI change as the system's state changes?
• **Accessibility** -- is the interface usable with keyboard, screen reader, or at different sizes?

Phase 1: Initial Reconnaissance

**Goal:** Navigate to the root URL, capture the landing page, and identify the application type, auth requirements, and available affordances.

1.1 Landing Page Capture

# Navigate to root URL and screenshot
# (Using Playwright as reference; adapt to available browser automation)

const page = await browser.newPage();
await page.goto(ROOT_URL, { waitUntil: 'networkidle' });
await page.screenshot({ path: 'workspace/raw/runtime/visual/screenshots/001-landing.png', fullPage: true });

1.2 Initial Assessment

Document:

• **Application type** -- SPA, MPA, dashboard, wizard, documentation site, etc.
• **Authentication** -- does the landing page require login? Is there a signup flow?
• **Primary navigation** -- top nav, sidebar, hamburger menu, tabs, breadcrumbs?
• **Visible affordances** -- buttons, links, forms, search bars, dropdowns visible on the landing page
• **Branding and layout** -- header, footer, sidebar, content area dimensions

1.3 Auth Handling

If authentication is required: 1. Screenshot the login page 2. Document the auth method (username/password, OAuth, SSO, API key) 3. If test credentials are available, authenticate and screenshot the post-login state 4. If no credentials are available, document the gate and explore only the unauthenticated surface

Phase 2: Navigation Mapping

**Goal:** Click every navigation element, screenshot each page, and document the complete navigation tree.

2.1 Identify Navigation Elements

// Extract all navigation links
const navLinks = await page.$$eval('nav a, [role="navigation"] a, .sidebar a, .menu a, header a', 
  links => links.map(a => ({ text: a.textContent.trim(), href: a.href }))
);

2.2 Systematic Traversal

For each navigation element: 1. Click the element (or navigate to the href) 2. Wait for the page to settle (network idle or DOM stable) 3. Take a full-page screenshot 4. Record the URL, page title, and visible heading 5. Identify sub-navigation elements on the new page

for (const [index, link] of navLinks.entries()) {
  await page.goto(link.href, { waitUntil: 'networkidle' });
  await page.screenshot({ 
    path: `workspace/raw/runtime/visual/screenshots/nav-${String(index).padStart(3, '0')}-${slugify(link.text)}.png`,
    fullPage: true 
  });
}

2.3 Navigation Tree Output

Write to `workspace/raw/runtime/visual/navigation-map.md`:

## Navigation Tree

- **Home** (`/`) -- screenshot: 001-landing.png
  - **Dashboard** (`/dashboard`) -- screenshot: nav-001-dashboard.png
    - **Analytics** (`/dashboard/analytics`) -- screenshot: nav-002-analytics.png
    - **Reports** (`/dashboard/reports`) -- screenshot: nav-003-reports.png
  - **Settings** (`/settings`) -- screenshot: nav-004-settings.png
    - **Profile** (`/settings/profile`) -- screenshot: nav-005-profile.png
    - **Billing** (`/settings/billing`) -- screenshot: nav-006-billing.png

Phase 3: Interaction Documentation

**Goal:** For each page, identify interactive elements, interact with them, and capture before/after screenshots documenting the system's feedback.

3.1 Element Inventory

For each page, identify:

• **Forms** -- text inputs, selects, checkboxes, radio buttons, textareas, file uploads
• **Buttons** -- submit buttons, action buttons, toggle buttons
• **Dropdowns** -- select menus, custom dropdown components
• **Modals/dialogs** -- elements that trigger overlay content
• **Expandable sections** -- accordions, collapsible panels, "show more" links
• **Interactive widgets** -- date pickers, sliders, color pickers, drag-and-drop zones

const interactiveElements = await page.$$eval(
  'button, input, select, textarea, [role="button"], [role="tab"], [onclick], a[href="#"]',
  els => els.map(el => ({
    tag: el.tagName,
    type: el.type || '',
    text: el.textContent?.trim().substring(0, 50),
    id: el.id,
    name: el.name,
    ariaLabel: el.getAttribute('aria-label'),
  }))
);

3.2 Interaction Capture

For each interactive element:

1. **Before screenshot** -- capture the page state before inter