Workflows

PEN now exposes a workflow-first entry point for the most common debugging loops, and the lower-level tools still chain together naturally when you need a more manual investigation. Start with pen_workflow when you want guided verdicts and next steps, then fall back to the manual patterns below when you need finer control.

Workflow-First Entry Points

slow-page-triage

Use this when a page feels slow and you need one pass across startup cost, render-blocking resources, Web Vitals, and CPU hotspots. The workflow returns a single verdict plus the most likely next step instead of leaving the LLM to infer the chain from raw outputs.

js-bloat-check

Use this when you suspect oversized bundles, weak code splitting, or scripts that load far more code than they use. When a URL is provided, the workflow starts coverage before navigation so the result reflects page-load JavaScript, not just idle runtime state.

accessibility-pass

Use this when you want a fast accessibility sweep for missing alt text, unlabeled controls, heading-order problems, and missing document language. It is intentionally lightweight and still points you back to Lighthouse and manual keyboard or screen-reader testing for deeper validation.

Manual Investigation Patterns

Memory Leak Investigation

1. Force GC to get a clean baseline
2. Take snapshot A
3. Have the user reproduce the suspected leak (navigate, open/close a modal, etc.)
4. Take snapshot B
5. Diff the two snapshots — PEN shows new objects, grown objects, and total delta

The diff highlights retained objects that grew between the two snapshots — those are your leak suspects. PEN also includes a percentage change and a qualitative assessment (e.g. "minor growth", "significant growth", "critical growth") to help the LLM quickly gauge severity. From there, the LLM can reason about the object types and suggest what’s holding the reference.

Tip: If you'd rather track allocations over time instead of taking two manual snapshots, use pen_heap_track with action: "start", reproduce the problem, then action: "stop".

Page Load Optimization

1. Navigate to the target page
2. Capture a Chrome trace during load
3. Analyze the trace for long tasks (>50ms), LCP, CLS, and slow resources
4. Check the network waterfall for large assets, slow requests, and render-blocking resources
5. Measure Core Web Vitals for the final score

That gives the LLM the full picture: trace-level timing, network bottlenecks, and Web Vitals scores in one pass.

Console Debugging

1. Start console capture to wire up the CDP listener
2. Have the user reproduce the issue
3. Pull error messages — filtering by level=error keeps noise down. You can also use textFilter to search for specific strings (case-insensitive substring match) across all message text.

Console entries include source URLs, line numbers, and stack traces for exceptions. Buffer holds 1,000 messages; oldest 100 get evicted when it fills up.

Full Page Audit

1. Navigate to the page
2. Run Lighthouse for a high-level score (performance, accessibility, SEO, best practices)
3. Capture a trace for the detailed timeline
4. Analyze the trace to pinpoint exactly what Lighthouse flagged

Lighthouse tells you what's wrong. The trace tells you why and where in the timeline.

Bundle Audit

1. Run pen_js_coverage with the navigate parameter set to the page URL — PEN starts coverage, navigates, collects, and stops internally
2. Run pen_css_coverage the same way to see which CSS rules are unused

This surfaces dead code. The LLM can then recommend code splitting or tree-shaking based on what's unused. Both coverage tools are single-call — they handle start, navigate, collect, and stop in one invocation.

Multi-Tab Profiling

1. List all browser tabs
2. Switch to the target tab
3. Profile CPU on that tab
4. Grab performance metrics

Handy when your app spans multiple tabs or you need to compare performance across pages.

Trace-Driven Analysis

Record a raw trace, then feed it to pen_trace_insights for a structured breakdown. No need to leave the conversation to analyze the file. You get:

• Long tasks (>50ms threshold)
• Layout shifts (CLS contributors)
• Largest Contentful Paint timing
• Slowest resources
• Frame timing and dropped frames (>33.3ms = below 30fps)

Network Performance

1. Enable network capture (optionally disable cache)
2. Interact with the page — navigate, click, scroll
3. View the waterfall to spot slow requests, large assets, or 4xx/5xx errors. Use statusFilter (4xx, 5xx, error, or an exact status code) and urlFilter (case-insensitive substring) to narrow results.
4. Drill into a specific request for full headers, timing, and body details

Device Simulation

1. Set device emulation (e.g., iPhone 14 with 4G network + 4x CPU throttle)
2. Navigate to the page
3. Measure Web Vitals under throttled conditions
4. Capture a trace to see what's slow on constrained hardware

Network presets: 3G (563ms latency, 188KB/s down), slow-3g (2000ms, 50KB/s), 4G (170ms, 500KB/s), WiFi (2ms, 3.75MB/s), offline (all connectivity disabled). You can also set offline: true independently of any preset to simulate airplane mode.

Tool ID Flow

Some tools produce IDs consumed by downstream tools:

IDs are opaque strings (or file paths for traces). They stay valid until PEN restarts or the thing they reference goes away (tab closed, page navigated, etc.).