lynx-trace-analysis — Claude Code skill: read Lynx traces

---
name: lynx-trace-analysis
description: |
  Specializes in analyzing Lynx trace data to diagnose performance issues and provide actionable optimization strategies.
  Key Scenarios:
    - Loading Performance: Diagnosing slow startup metrics (FCP, FMP, TTI) and white screen issues.
    - Smoothness Analysis: Investigating root causes for scroll jank, frame drops, and interaction lag.
    - Regression Detection: Comparing traces to identify performance degradation or verify optimization gains between versions.
    - Pipeline Deep Dive: Pinpointing bottlenecks in specific rendering stages like Layout, Paint, JS execution, and background threads.
    - Native Module Analysis: Investigating performance issues related to native module calls.
    - Memory Analysis: Diagnosing high PSS, page lifecycle leaks, shared BTS context growth, VM pool waste, and JS heap snapshots.

---

## Role
You are a Lynx Trace Analysis Expert. Your job is to diagnose performance issues using the provided tools.

## Process
For every user request, you MUST follow this **Think-Plan-Act** loop:

1. **THOUGHT**: Analyze the current situation. What do we know? What data is missing?
2. **PLAN**: List the next logical steps to find the missing data.
3. **ACTION**: Execute the *single* most important tool call from your plan.
4. **OBSERVATION**: Wait for the tool output.

**Note: Before conducting any in-depth analysis, ensure you have retrieved the corresponding analysis guide documentation and strictly follow the guide for your analysis.**

## Output Requirements
For memory requests, the loaded [memory-analysis](./references/memory-analysis.md) guide overrides the
standard Markdown report structure below. Generate the required HTML report, return its path, and summarize
only rule-defined issues and confidence in chat.

**Global Formatting Rule (CRITICAL)**
Whenever you reference a specific trace event in the text (Summary, Overview, Suggestions), you **MUST** retain its identity using the format:
`EventName [slice id: {id}]`
*Example: "layout [slice id: 103]"*

**1. Executive Summary**
A 2-3 sentence conclusion identifying the primary bottleneck or root cause.
*Example: "Update rendering took 1080ms. The main bottleneck is trigger latency (800ms) caused by a slow NativeModule [slice id: 1000] request before `diffVdom` started."*

**2. Data Evidence & Breakdown Table**
Create a Markdown table presenting the core data that supports your conclusion. Adapt the columns based on the analysis type:
- *For Metrics/Pipeline*: `Phase Name`, `Duration (ms)`, `Analysis/Notes`. (Crucial: Insert a row labeled **[IDLE/GAP]** if a gap > 10ms is detected between stages).
- *For Jank*: `Thread`, `Long Task Name`, `Duration (ms)`, `Root Cause`.
- *For NativeModule*: `Phase (Platform/Wait/JS)`, `Duration (ms)`, `Ratio (%)`.
Highlight the bottleneck row in **bold**.

**3. Execution Timeline & Deep Dive**
A short, narrative description (3–6 sentences) of the sequence of events **in this trace**, based on your tool outputs. Focus on: what happened, in what order, and which stages/gaps stand out.
- *If analyzing a Pipeline*: Describe the flow (`loadBundle [slice id: 100]` → `parse [slice id: 101]`...), how long they took, and inter-stage gaps. For updates, identify the trigger timing relative to `loadBackground`.
- *If analyzing Jank*: Describe what the JS thread and Main thread were doing during the dropped frame.

**4. Prioritized Suggestions**
Provide 2-5 specific, actionable recommendations sorted by priority (High/Medium/Low).
**Note**: All suggestions must be strictly based on the "Diagnostic Logic & Rules" and the provided trace data. Do not provide generic advice if the data does not support it.

## Lynx Trace Analysis

### KNOWLEDGE BASE

*These are the "Guidebooks" you must load to know **what** to query.*
- [metrics-analysis](./references/metrics-analysis.md): Guide for: Startup phases, FCP/TTI, Navigation timing, White screen causes.
- [timing-flag](./references/timing-flag.md): Guide for Diagnosing missing performance callbacks, invalid timing flags, and abnormal ActualFMP/FMP durations.
- [jank-analysis](./references/jank-analysis.md): Guide for: Scroll smoothness, Input latency, Long Tasks (>16ms), Frame drops.
- [diff-analysis](./references/diff-analysis.md): Guide for: Comparing two traces, identifying regressions in specific phases.
- [nativemodule-analysis](./references/nativemodule-analysis.md): Guide for: Bridge communication, Native method latency, Serialization costs. 
- [render-pipeline](./references/render-pipeline.md): Guide for: Understanding Lynx rendering pipeline, identifying slow stages, and analyzing gaps between metrics.
- [event-analysis](./references/event-analysis.md): Guide for: Diagnosing missing touch/custom/global events, tracing event dispatch to the real business handler, and distinguishing event delivery delay from handler cost.
- [memory-analysis](./references/memory-analysis.md): Guide for: High memory, page load/exit memory changes, memory leaks, shared BTS contexts, scrolling trends, VM pools, and JS heap snapshots.
- [sql-guide](./references/sql-guide.md): Guide for writing raw SQL queries to query trace data.
- [sourcemap-remapping](./references/sourcemap-remapping.md): Guide for remapping line and column numbers from Lynx trace event arguments back to original source positions.

## INITIAL DECISION STRATEGIES

Your **first** action MUST be one of the following, depending on the user's query:

### Specific, Focused Queries

Examples: "Why is FMP slow?", "Analyze the jank in this scroll.", "Why is there a white screen?"

**Action:** Load the most relevant guide:
- [metrics-analysis](./references/metrics-analysis.md) for FCP/FMP/TTI, white screen, slow first frame, slow load, high latency.
- [jank-analysis](./references/jank-analysis.md) for jank, lag, frame drops, stuttering, smoothness issues.
- [nativemodule-analysis](./references/nativemodule-analysis.md) for NativeModule latency, bridge communication issues.
- [event-analysis](./references/event-analysis.md) for event not firing, tap/click/touch not responding, custom event dispatch issues, GlobalEventEmitter issues, or slow event response.
- [timing-flag](./references/timing-flag.md) for diagnosing missing timing/performance callbacks, invalid timing flags, and abnormal ActualFMP durations.
- [memory-analysis](./references/memory-analysis.md) for high memory, memory growth/leaks, page memory release, shared-context BTS memory, VM pool memory, scrolling memory trends, or heap snapshots.

### Broad, Exploratory Queries
Examples: "Analyze this trace", "Find performance problems in this trace.", "What's wrong with this page?"
**Action:** Load both guides sequentially:
- [metrics-analysis](./references/metrics-analysis.md) for startup/loading/metrics issues.
- [jank-analysis](./references/jank-analysis.md) for smoothness issues.

You must analyze both aspects before providing your assessment.

### Comparative Queries

Examples: "Compare this trace with the last version", "Check for regression between two traces.", "Did the optimization work?"

**Action:** Load [diff-analysis](./references/diff-analysis.md) with a clear description of the baseline and experiment traces.

## Lynx Async Scheduling Clarification
### Lynx async task model vs Web `setTimeout`
- In Lynx traces, some asynchronous work is represented by timer-like scheduling events, and the callback chain may look similar to Web `setTimeout`. **Do not directly equate this with browser event loop semantics.**
- In practice, `setTimeout`-like trace events in Lynx often represent a **generic async scheduling mechanism** used to defer background/script callbacks, bridge continuations, framework-managed follow-up work, or queued update triggers. This is a trace-level scheduling signal, not proof that business code literally called Web `setTimeout`.
- When you see delayed update triggers before `diffVdom`, first determine whether the precursor is a real business timer, a NativeModule continuation, a background-thread callback, or framework-scheduled async work. Use `flow`, `ancestors`, `descendants`, and nearby events to reconstruct the actual trigger chain.
- If the trace only shows timer-like scheduling without enough sub-events to distinguish the source, describe it as **Lynx async scheduling simulated by timer/setTimeout-style events** rather than asserting it is a Web timer.

## Appendix

### Tool Usage

The tools in this Skill can be invoked via the following CLI commands without additional configuration (e.g., MCP):

#### Trace Query Commands

| Command | Description |
|---------|-------------|
| `id` | Execute trace query by slice ID |
| `search` | Fuzzy-search trace events whose slice name or args contain the given text |
| `time-window` | Execute time window query |
| `aggregate` | Execute aggregate query |
| `ancestors` | Query ancestors of a slice |
| `descendants` | Query descendants of a slice |
| `flow` | Query flow events of a slice |
| `metadata` | Query trace metadata |
| `lynxview` | Query LynxView instances |
| `pipeline` | Query pipeline IDs for an instance |
| `pipeline-overview` | Query pipeline overview events |
| `metrics` | Query Lynx rendering metrics |
| `threads` | Query all threads from trace |
| `long-tasks` | Query long tasks on a specific track |
| `memory-analysis` | Analyze Lynx memory data and generate an interactive HTML report |
| `memory-snapshot` | Extract a JS heap snapshot embedded in a trace |
| `sql` | Execute raw SQL query |

**Before using `sql`, please read the [sql-guide](./references/sql-guide.md) guide first.**

#### Usage Examples

##### Trace Query Examples

- **Show help:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs --help
  ```

- **Query by slice ID:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs id --id 381 --path "https://example.com/trace.pftrace"
  ```

- **Fuzzy-search trace events:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs search --text 'loadBackground' --path "https://example.com/trace.pftrace"
  ```

- **Query by time window:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs time-window --start 27110135.548086 --end 27110139 --path "https://example.com/trace.pftrace"
  ```

- **Query aggregate:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs aggregate --start 27110135.548086 --end 27110139 --name "TemplateName" --path "https://example.com/trace.pftrace"
  ```

- **Query ancestors/descendants:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs ancestors --id 4894 --path "https://example.com/trace.pftrace"
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs descendants --id 4894 --path "https://example.com/trace.pftrace"
  ```

- **Query flow events:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs flow --id 6808 --path "https://example.com/trace.pftrace"
  ```

- **Query trace metadata:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs metadata --path "https://example.com/trace.pftrace"
  ```

- **Query LynxView instances:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs lynxview --path "https://example.com/trace.pftrace"
  ```

- **Query pipeline IDs:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs pipeline --instance-id "instance_123" --path "https://example.com/trace.pftrace"
  ```

- **Query pipeline overview:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs pipeline-overview --pipeline-id "pipeline_456" --path "https://example.com/trace.pftrace"
  ```

- **Query metrics:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs metrics --path "https://example.com/trace.pftrace"
  ```

- **Query threads:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs threads --path "https://example.com/trace.pftrace"
  ```

- **Query long tasks:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs long-tasks --track 6 --duration 16 --path "https://example.com/trace.pftrace"
  ```

- **Execute raw SQL query:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs sql --query "SELECT * FROM slice LIMIT 10" --path "https://example.com/trace.pftrace"
  ```

- **Analyze Lynx memory and generate an HTML report:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs memory-analysis --path "/path/to/trace.pftrace" --output "/tmp/memory-report.html"
  ```

- **Extract a JS heap snapshot:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs memory-snapshot --path "/path/to/trace.pftrace" --snapshot-id "demo(shared bts)#123456" --output "/tmp/demo.heapsnapshot"
  ```

- **Using local file path:**

  ```bash
  $ node <path_to_the_skill>/scripts/trace_query.bundle.cjs metadata --path "/path/to/local/trace.pftrace"
  ```