zeitzeuge 0.7.4 → 0.8.0

package/dist/cli.js

@@ -602,28 +602,31 @@ var VERIFICATION_RULES = `## Verification rules (mandatory for every finding)
 2. **Copy code verbatim** — beforeCode must be copied exactly from the file you
    read, not paraphrased. Line numbers must match what you observed.
 3. **Provide a working fix** — afterCode must be a complete drop-in replacement
-   that compiles, preserves the function signature, and only fixes the perf issue.
-4. **Never omit beforeCode/afterCode** — every finding MUST have both fields set.`;
+   that compiles, preserves the EXACT function signature, and only fixes the perf issue.
+4. **Never omit beforeCode/afterCode** — every finding MUST have both fields set.
+5. **Do NOT change sync to async** — if a function is synchronous, afterCode must
+   also be synchronous. Replace the inefficient implementation with a faster sync
+   alternative (e.g., use crypto.createHash instead of a manual loop). Mention the
+   async alternative in the description, but keep afterCode as a sync drop-in.`;
 var OUTPUT_FORMAT = `## Output requirements
 
-- Report ALL findings you discover — typically 3–8 per subagent. Do NOT
-  stop at 2-3 findings. Exhaustively analyze every function in every file.
+- Report ALL findings within YOUR scope — typically 3–5 per subagent.
+  Exhaustively analyze every function but stay within your assigned categories.
 - Each finding MUST have sourceFile, beforeCode, and afterCode
 - Be specific — name exact files, functions, and line numbers
 - Provide concrete code-level fixes, not generic advice
+- Do NOT report findings about test files — only about application source files
 
 ### CRITICAL: Multiple findings per function and per file
 
-- A single function CAN have multiple distinct issues — report each as a
-  SEPARATE finding. For example, hashPassword() might both block the event
-  loop AND allocate a TextEncoder on every call — these are TWO findings
-  with different categories.
+- A single function CAN have multiple distinct issues WITHIN YOUR SCOPE —
+  report each as a SEPARATE finding with a different category.
 - A single file often has MANY issues across different functions. Read the
-  ENTIRE file top-to-bottom and report EVERY issue you find, not just the
-  first one.
+  ENTIRE file top-to-bottom and report EVERY issue you find within your scope.
 - If function A calls function B and both have issues, report findings for
   BOTH functions separately.
-- Do NOT skip issues you consider "minor" — report them with severity: info.`;
+- Do NOT skip issues you consider "minor" — report them with severity: info.
+- Do NOT report issues that belong to another subagent's scope.`;
 var FINDING_CATEGORIES = `## Finding categories
 
 Each finding MUST use one of these EXACT category values — do NOT invent new categories:
@@ -671,7 +674,7 @@ var STRUCTURED_OUTPUT_FIELDS = `## Structured output fields — REQUIRED for eve
 
 Every finding MUST include ALL of these fields:
 
-- \`sourceFile\` — (REQUIRED) the workspace path (e.g. /src/utils/parser.ts or /scripts/app.js)
+- \`sourceFile\` — (REQUIRED) the workspace path (e.g. src/utils/parser.ts or scripts/app.js)
 - \`lineNumber\` — (REQUIRED) the 1-based line number, verified by reading the file
 - \`confidence\` — \`high\` if you read the source, \`medium\` if strongly suggested,
   \`low\` if inferred
@@ -695,17 +698,46 @@ Every finding MUST include ALL of these fields:
   Copy the COMPLETE function (or the complete relevant section of 5-30 lines).
   Do NOT use "..." or "// ..." to skip lines. Include the full code block.
 - afterCode must be a COMPLETE, WORKING replacement for the beforeCode block:
-  - Same function signature, same exports, same return type
+  - SAME function signature — same name, same parameters, same return type
+  - SAME sync/async — if the original is sync, afterCode MUST be sync. Do NOT
+    add async/await, Promises, or callbacks. Replace the slow implementation
+    with a faster synchronous alternative instead.
+  - SAME exports — if the function is exported, afterCode must also export it
   - Must compile and produce identical behavior except for the performance fix
   - Include ALL the code from beforeCode, not just the changed lines
   - If the fix requires adding a module-level constant (e.g., hoisting a RegExp or
-    TextEncoder), include that declaration in afterCode
-  - For blocking operations: the fix should actually make the operation non-blocking
-    (e.g., use async APIs, yield to the event loop, or use workers)
-  - For excessive instantiation: hoist the construction to module level and reuse it
+    TextEncoder), include that declaration ABOVE the function in afterCode
+  - For blocking CPU loops: replace with a faster sync algorithm (e.g., use
+    crypto.createHash() instead of a manual loop). Mention async alternatives
+    in the finding description, not in afterCode.
+  - For excessive instantiation: hoist the construction to module level and reuse it.
+    Show the module-level const AND the modified function in afterCode.
+  - For listener leaks: show the fix (e.g., .once() instead of .on(), or return
+    an unsubscribe function). The beforeCode/afterCode should show the same function
+    with only the listener fix changed.
 - afterCode must NOT be a diff, pseudocode, or description of changes
 - If you cannot provide a concrete fix, still include beforeCode and describe
-  the fix approach in afterCode as a code comment within the actual code`;
+  the fix approach in afterCode as a code comment within the actual code
+
+### Code fix quality rules
+
+1. **Named functions for event handlers**: NEVER use anonymous functions with
+   .on() or .addEventListener(). Always define a named function or const so
+   it can be removed with .off(event, handler). Example:
+   - BAD:  emitter.on('change', () => { cache = null; })
+   - GOOD: const invalidateCache = () => { cache = null; };
+           emitter.on('change', invalidateCache);
+2. **Surgical listener removal**: Use .off(event, specificHandler) instead of
+   .removeAllListeners(). The cleanup/reset function must remove the EXACT
+   handler that was added.
+3. **Complete guard logic**: If you add a guard flag (e.g., listenerRegistered),
+   the cleanup function MUST reset the flag AND remove the specific listener.
+4. **Include surrounding context**: If the fix adds module-level variables
+   (guard flags, hoisted constants, named handlers), include ALL of them in
+   afterCode so it is self-contained.
+5. **Preserve existing functions**: If the original file has a cleanup/reset
+   function, update it in afterCode to properly undo whatever your fix added.
+   Do NOT ignore existing cleanup functions.`;
 // ../utils/src/prompts/file-list.ts
 function buildFileListPromptSection(config) {
   const { dataFiles, sourceFiles, testFiles, additionalSections } = config;
@@ -762,29 +794,1118 @@ function insertFileListIntoPrompt(prompt, fileSection) {
 ` + prompt.slice(firstHeadingIdx);
 }
 // ../utils/src/workspace/builder.ts
-import { FilesystemBackend } from "deepagents";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-function createWorkspaceFromFiles(files, prefix = "zeitzeuge-workspace-") {
-  const tempDir = mkdtempSync(join(tmpdir(), prefix));
-  for (const [filePath, content] of Object.entries(files)) {
-    const relPath = filePath.startsWith("/") ? filePath.slice(1) : filePath;
-    const fullPath = join(tempDir, relPath);
-    mkdirSync(join(fullPath, ".."), { recursive: true });
-    writeFileSync(fullPath, content, "utf-8");
-  }
-  const backend = new FilesystemBackend({
-    rootDir: tempDir,
-    virtualMode: true
-  });
-  const cleanup = () => {
+import { VfsSandbox } from "@langchain/node-vfs";
+
+class PerfAgentSandbox extends VfsSandbox {
+  static #toRelative(p) {
+    const stripped = p.startsWith("/") ? p.slice(1) : p;
+    return stripped || ".";
+  }
+  async read(filePath, offset = 0, limit = 500) {
+    return super.read(PerfAgentSandbox.#toRelative(filePath), offset, limit);
+  }
+  async lsInfo(dirPath) {
+    return super.lsInfo(PerfAgentSandbox.#toRelative(dirPath));
+  }
+  async grepRaw(pattern, searchPath = "/", glob = null) {
+    return super.grepRaw(pattern, PerfAgentSandbox.#toRelative(searchPath), glob);
+  }
+  async globInfo(pattern, searchPath = "/") {
+    return super.globInfo(pattern, PerfAgentSandbox.#toRelative(searchPath));
+  }
+  static async create(options) {
+    const sandbox = new PerfAgentSandbox(options);
+    await sandbox.initialize();
+    return sandbox;
+  }
+}
+async function createWorkspaceFromFiles(files) {
+  const sandbox = await PerfAgentSandbox.create({ initialFiles: files });
+  const cleanup = async () => {
     try {
-      rmSync(tempDir, { recursive: true, force: true });
+      await sandbox.stop();
     } catch {}
   };
-  return { backend, cleanup, tempDir };
+  return { backend: sandbox, cleanup };
+}
+// ../utils/src/skills/data-scripting.ts
+var SKILL_MD = `---
+name: data-scripting
+description: Use this skill when you need to analyze JSON data files in the workspace. Provides instructions for writing Node.js scripts to query, filter, aggregate, and cross-reference data files instead of reading them raw. Includes helper scripts and data file schemas.
+---
+
+# Data Scripting
+
+## Overview
+
+You have a full Node.js runtime available via execute_command. Instead of
+reading large JSON data files with read_file (which consumes many tokens),
+write short scripts that extract exactly what you need.
+
+## When to use scripts vs. read_file
+
+- **read_file**: Source code files you need to see verbatim for
+  beforeCode/afterCode, or small files (<50 lines)
+- **Scripts**: JSON data files, any file >100 lines, cross-referencing
+  multiple files, computing aggregations, filtering by thresholds
+
+## How to run a script
+
+IMPORTANT: All file paths in scripts must use relative paths (no leading
+\`/\`). The execute_command tool runs with the workspace as the current
+directory, so \`fs.readFileSync('hot-functions/application.json')\` resolves
+to \`<workspace>/hot-functions/application.json\`.
+
+Option 1 — inline:
+execute_command: node -e "
+  const data = JSON.parse(require('fs').readFileSync('path/to/file', 'utf8'));
+  const results = data.filter(x => x.duration > 100);
+  console.log(JSON.stringify(results, null, 2));
+"
+
+Option 2 — use a pre-built helper:
+execute_command: node skills/data-scripting/helpers/top-items.js hot-functions/application.json selfTime 10
+
+Option 3 — write a custom script:
+write_file: tmp/my-analysis.js
+execute_command: node tmp/my-analysis.js
+
+## Pre-built helper scripts
+
+### skills/data-scripting/helpers/top-items.js
+Usage: \`node top-items.js <file> <sortField> [limit]\`
+Reads a JSON array, sorts by the given field descending, prints top N items.
+
+### skills/data-scripting/helpers/cross-reference.js
+Usage: \`node cross-reference.js <file1> <field1> <file2> <field2>\`
+Finds items in file1 whose field1 value also appears as field2 in file2.
+
+## Data file schemas
+
+See skills/data-scripting/schemas.md for the JSON structure of every
+data file in this workspace. Read it before writing custom scripts.
+`;
+var SCHEMAS_MD = `# Workspace Data File Schemas
+
+---
+# Workspace files
+---
+
+## summary.json
+{
+  totalTests: number,
+  totalDuration: number,       // ms
+  passCount: number,
+  failCount: number,
+  profileCount: number,
+  slowestFile: string | null,  // file:// URL
+  slowestFileDuration: number,
+  totalGcTime: number,
+  gcPercentage: number
+}
+
+## hot-functions/application.json
+Array of application-code hot functions (filtered to sourceCategory "application"):
+{
+  functionName: string,
+  workspacePath: string,       // e.g. "/src/services/crypto.ts" (has leading /)
+  lineNumber: number,
+  columnNumber: number,
+  selfTime: number,            // ms of CPU self-time
+  totalTime: number,           // ms including callees
+  hitCount: number,
+  selfPercent: number,         // % of total profile duration
+  sourceCategory: "application",
+  sourceSnippet?: string,      // source code context around the hot line
+  callerChain?: [{ functionName, workspacePath, lineNumber }]
+}
+
+## hot-functions/dependencies.json
+Same structure as hot-functions/application.json but sourceCategory "dependency".
+
+## hot-functions/global.json
+All hot functions across all categories (application, dependency, framework, unknown).
+Same item structure. Can be very large (2000+ lines).
+
+## scripts/application.json
+Per-script summary for application code:
+[{ workspacePath: string, selfTime: number, selfPercent: number, functionCount: number }]
+
+## scripts/dependencies.json
+Same structure as scripts/application.json but for dependency scripts.
+
+## src/index.json
+Maps source file paths to their hot functions. Key = workspacePath, value = array:
+{
+  "/src/services/notification-service.ts": [
+    { functionName: string, lineNumber: number, selfTime: number, selfPercent: number }
+  ],
+  "/src/utils/crypto.ts": [...]
+}
+Use this to know WHICH source files have CPU-hot functions.
+
+## listener-tracking.json
+{
+  eventTargetCounts: {},       // browser EventTarget counts (usually empty in Node)
+  emitterCounts: {             // keyed by event name
+    "<eventName>": { addCount: number, removeCount: number },
+    ...
+  },
+  exceedances: [{              // maxListeners threshold exceeded
+    targetType: string,        // e.g. "EventEmitter"
+    eventType: string,         // e.g. "task:changed"
+    listenerCount: number,     // current count that exceeded threshold
+    threshold: number,         // the maxListeners value (default 10)
+    stack: string              // stack trace showing where listener was added
+  }]
+}
+
+## metrics/current.json
+Comprehensive pre-computed metrics (large file):
+{
+  version: number,
+  timestamp: string,
+  suite: { totalDuration, totalTests, passCount, failCount, averageTestDuration,
+           medianTestDuration, p95TestDuration, slowestTestDuration, slowestTestName },
+  cpu: { gcPercentage, gcTime, idlePercentage, idleTime, applicationTime,
+         applicationPercent, dependencyTime, dependencyPercent, testFrameworkTime,
+         testFrameworkPercent },
+  files: { "<file:// URL>": { duration, testCount, setupTime, gcPercentage } },
+  tests: { "<file::testName>": { duration, status } },
+  hotFunctions: [{ key, functionName, scriptUrl, lineNumber, selfTime, selfPercent,
+                   sourceCategory }],
+  listenerTracking: { eventTargetCounts, emitterCounts, exceedances }
+}
+
+## timing/overview.json
+Array of per-file timing data:
+[{
+  file: string,                // file:// URL
+  duration: number,
+  testCount: number,
+  passCount: number,
+  failCount: number,
+  setupTime: number,
+  tests: [{ name: string, duration: number, status: string }]
+}]
+
+## timing/slow-tests.json
+Array of slow tests sorted by duration descending:
+[{ file: string, name: string, duration: number }]
+
+## profiles/index.json
+Manifest mapping test files to their CPU profile paths:
+[{ testFile: string, profilePath: string }]
+
+## profiles/<file>.json
+Per-test-file profile summary:
+{
+  profilePath: string,
+  duration: number,
+  sampleCount: number,
+  hotFunctions: [{
+    functionName, lineNumber, columnNumber, selfTime, totalTime,
+    hitCount, selfPercent, callerChain, sourceCategory, workspacePath
+  }]
+}
+
+---
+# Browser workspace files (CLI agent only — not present in Vitest workspaces)
+---
+
+## heap/summary.json
+{
+  metadata: { url, capturedAt, totalSize, nodeCount, edgeCount },
+  largestObjects: [{ name, type, selfSize, retainedSize, retainerPath: string[] }],
+  typeStats: [{ type, count, totalSize, avgSize }],
+  constructorStats: [{ constructor, count, totalSize, avgSize }],
+  detachedNodes: { count, totalSize, examples: [{ name, retainerPath }] },
+  closureStats: { count, totalSize, topClosures: [{ name, contextSize, retainerPath }] }
+}
+
+## trace/summary.json
+{
+  url: string,
+  timing: { loadComplete, firstContentfulPaint, largestContentfulPaint, totalBlockingTime, longTasks: [...] },
+  requestCount: number,
+  totalTransferSize: number,
+  totalDecodedSize: number,
+  renderBlockingResources: [{ url, type, size, duration, path }],
+  resourceBreakdown: { scripts: { count, totalSize }, stylesheets: {...}, fonts: {...}, images: {...}, other: {...} }
+}
+
+## trace/runtime/blocking-functions.json
+Array of (up to 50 entries, sorted by duration descending):
+{
+  functionName: string,
+  scriptUrl: string,           // URL of the script
+  lineNumber: number,
+  columnNumber: number,
+  duration: number,            // ms blocked on main thread
+  startTime: number,           // ms relative to navigation start
+  callStack: [{                // caller chain (array of objects, NOT strings)
+    functionName: string,
+    scriptUrl: string,
+    lineNumber: number
+  }],
+  category: string             // "scripting" | "layout" | "paint" | etc.
+}
+To get the workspace file path for a scriptUrl, extract the filename:
+  e.g. "https://example.com/static/abc123.js" -> "scripts/abc123.js"
+
+## trace/runtime/event-listeners.json
+Array of (only listeners with addCount > 0):
+{
+  eventType: string,
+  targetType: string,
+  addCount: number,
+  removeCount: number,
+  activeCount: number,
+  stackSnippets: string[]
+}
+
+## trace/runtime/summary.json
+{
+  totalEvents: number,
+  traceDuration: number,       // ms
+  mainThreadId: number,
+  frameBreakdown: { scripting, layout, paint, gc, other },  // all in ms
+  blockingFunctionCount: number,
+  listenerImbalances: number,
+  gcPauseCount: number,
+  gcTotalDuration: number,     // ms
+  frequentEventTypes: string[] // event types dispatched >10 times
+}
+
+## trace/runtime/frame-breakdown.json
+{
+  scripting: number,           // ms spent in script execution
+  layout: number,              // ms spent in layout calculations
+  paint: number,               // ms spent painting
+  gc: number,                  // ms spent in garbage collection
+  other: number                // ms spent in other tasks
+}
+
+## trace/network-waterfall.json
+Array of (sorted by startTime):
+{
+  url: string,
+  type: string,                // "Script" | "Stylesheet" | "Font" | "Document" | "Image"
+  status: number,
+  size: number,                // decoded size in bytes
+  startTime: number,           // ms from navigation start
+  endTime: number,
+  duration: number,
+  isRenderBlocking: boolean,
+  priority: string,
+  path: string | null          // workspace path to stored content (e.g. "/scripts/abc.js")
+}
+
+## trace/asset-manifest.json
+Array of all network assets:
+{
+  url: string,
+  type: string,
+  size: number,                // decoded size in bytes
+  duration: number,
+  isRenderBlocking: boolean,
+  stored: boolean,             // true if content was captured and stored
+  path: string | null          // workspace path if stored
+}
+
+## trace/runtime/raw-events.json
+Array of raw Chrome trace events (can be very large). Each entry has:
+{
+  name: string,                // event name (e.g. "FunctionCall", "Layout", "GCEvent")
+  cat: string,                 // category
+  ph: string,                  // phase ("X" = complete, "B"/"E" = begin/end)
+  ts: number,                  // timestamp in microseconds
+  dur: number,                 // duration in microseconds
+  tid: number,                 // thread ID
+  pid: number,                 // process ID
+  args: object                 // event-specific arguments
+}
+Only use for deep investigation — prefer the summary files first.
+`;
+var TOP_ITEMS_JS = `'use strict';
+
+const fs = require('fs');
+
+const [filePath, sortField, limitArg] = process.argv.slice(2);
+if (!filePath || !sortField) {
+  console.error('Usage: node top-items.js <file> <sortField> [limit]');
+  process.exit(1);
+}
+
+const limit = parseInt(limitArg, 10) || 10;
+
+let raw;
+try {
+  raw = fs.readFileSync(filePath, 'utf8');
+} catch (err) {
+  console.error(\`Error reading \${filePath}: \${err.message}\`);
+  process.exit(1);
+}
+
+let data;
+try {
+  data = JSON.parse(raw);
+} catch (err) {
+  console.error(\`Error parsing JSON from \${filePath}: \${err.message}\`);
+  process.exit(1);
+}
+
+if (!Array.isArray(data)) {
+  console.error(\`Expected a JSON array in \${filePath}, got \${typeof data}\`);
+  process.exit(1);
+}
+
+if (data.length > 0 && !(sortField in data[0])) {
+  console.error(\`Field "\${sortField}" not found in items. Available fields: \${Object.keys(data[0]).join(', ')}\`);
+  process.exit(1);
+}
+
+const sorted = data
+  .slice()
+  .sort((a, b) => (Number(b[sortField]) || 0) - (Number(a[sortField]) || 0))
+  .slice(0, limit);
+
+console.log(JSON.stringify(sorted, null, 2));
+`;
+var CROSS_REFERENCE_JS = `'use strict';
+
+const fs = require('fs');
+
+const [file1Path, field1, file2Path, field2] = process.argv.slice(2);
+if (!file1Path || !field1 || !file2Path || !field2) {
+  console.error('Usage: node cross-reference.js <file1> <field1> <file2> <field2>');
+  process.exit(1);
+}
+
+function readJsonArray(filePath) {
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    console.error(\`Error reading \${filePath}: \${err.message}\`);
+    process.exit(1);
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (err) {
+    console.error(\`Error parsing JSON from \${filePath}: \${err.message}\`);
+    process.exit(1);
+  }
+  if (!Array.isArray(data)) {
+    console.error(\`Expected a JSON array in \${filePath}, got \${typeof data}\`);
+    process.exit(1);
+  }
+  return data;
+}
+
+const data1 = readJsonArray(file1Path);
+const data2 = readJsonArray(file2Path);
+
+const lookupValues = new Set(data2.map(item => item[field2]));
+const matches = data1.filter(item => lookupValues.has(item[field1]));
+
+if (matches.length === 0) {
+  console.log(\`No items in \${file1Path} have \${field1} matching \${field2} values from \${file2Path}.\`);
+  process.exit(0);
+}
+
+console.log(\`Found \${matches.length} item(s) in \${file1Path} where \${field1} matches \${field2} in \${file2Path}:\\n\`);
+for (const item of matches) {
+  console.log(\`  [\${field1}=\${JSON.stringify(item[field1])}]\`);
+  console.log(JSON.stringify(item, null, 2));
+  console.log();
+}
+`;
+var DATA_SCRIPTING_SKILL_FILES = {
+  "skills/data-scripting/SKILL.md": SKILL_MD,
+  "skills/data-scripting/schemas.md": SCHEMAS_MD,
+  "skills/data-scripting/helpers/top-items.js": TOP_ITEMS_JS,
+  "skills/data-scripting/helpers/cross-reference.js": CROSS_REFERENCE_JS
+};
+// ../utils/src/skills/browser-analysis.ts
+var SKILL_MD2 = `---
+name: browser-analysis
+description: Use this skill when analyzing browser page-load performance data including Chrome traces, heap snapshots, network waterfalls, and runtime blocking functions. Provides pre-built analysis scripts for common browser performance patterns.
+---
+
+# Browser Analysis Scripts
+
+## Overview
+
+Pre-built scripts for analyzing browser performance data. Run these
+directly or use them as templates for custom analysis.
+
+## START HERE — Workspace overview
+
+Run this FIRST to get a prioritized summary of the entire workspace:
+
+execute_command: node skills/browser-analysis/helpers/analyze-browser-workspace.js
+
+Reads trace/summary.json, heap/summary.json, trace/runtime/summary.json,
+blocking-functions.json, event-listeners.json, and network-waterfall.json.
+Outputs:
+- Page load metrics (FCP, LCP, TBT, load time)
+- Heap snapshot overview (total size, detached DOM nodes, closures)
+- Runtime trace summary (blocking function count, GC stats, frame breakdown)
+- Top blocking functions with script locations
+- Listener imbalances
+- Render-blocking resources
+- Large resources (>100KB)
+- Full list of available source files with sizes
+
+Use this output to decide which source files to read and which scripts
+to run for deeper analysis.
+
+## Additional scripts
+
+### Analyze blocking functions (detailed)
+execute_command: node skills/browser-analysis/helpers/analyze-blockers.js [--threshold 50]
+
+Reads trace/runtime/blocking-functions.json, filters by duration threshold
+(default 50ms), and outputs a ranked summary with call stacks and script
+locations. Also identifies compound blockers.
+
+### Analyze network waterfall (detailed)
+execute_command: node skills/browser-analysis/helpers/analyze-waterfall.js
+
+Reads trace/network-waterfall.json and trace/summary.json, outputs:
+- Render-blocking resources with sizes and durations
+- Large scripts (>100KB) with workspace paths
+- Sequential chains that could be parallelized
+- Uncompressed resources
+
+### Analyze heap snapshot (detailed)
+execute_command: node skills/browser-analysis/helpers/analyze-heap.js
+
+Reads heap/summary.json, outputs:
+- Detached DOM nodes with retainer paths
+- Top 10 largest retained objects
+- Constructor hotspots
+- Closures with large retained sizes
+
+### Find source code patterns
+execute_command: node skills/browser-analysis/helpers/find-patterns.js [--pattern addEventListener]
+
+Searches source files for performance anti-patterns.
+
+## Key data files
+
+- heap/summary.json — parsed V8 heap snapshot (detached nodes, retained objects, closures)
+- trace/summary.json — page load metrics, render-blocking resources, resource breakdown
+- trace/network-waterfall.json — every network request with timing, size, priority
+- trace/asset-manifest.json — index of all assets with stored file paths
+- trace/runtime/summary.json — runtime trace overview (frame breakdown, GC stats)
+- trace/runtime/blocking-functions.json — main-thread blocking functions with call stacks
+- trace/runtime/event-listeners.json — event listener add/remove counts
+- trace/runtime/frame-breakdown.json — time in scripting vs layout vs paint vs GC
+- scripts/*.js — actual JavaScript source files captured during page load
+- styles/*.css — actual CSS source files
+- html/document.html — the HTML document
+
+## Writing custom scripts
+
+Read skills/data-scripting/schemas.md for JSON structures, then write
+scripts that load and query the data.
+`;
+var ANALYZE_BROWSER_WORKSPACE_JS = `'use strict';
+
+var fs = require('fs');
+
+function tryRead(path) {
+  try { return JSON.parse(fs.readFileSync(path, 'utf8')); }
+  catch (_) { return null; }
 }
+
+var traceSummary = tryRead('trace/summary.json');
+var heapSummary = tryRead('heap/summary.json');
+var rtSummary = tryRead('trace/runtime/summary.json');
+var waterfall = tryRead('trace/network-waterfall.json');
+var assetManifest = tryRead('trace/asset-manifest.json');
+var blockingFunctions = tryRead('trace/runtime/blocking-functions.json');
+var eventListeners = tryRead('trace/runtime/event-listeners.json');
+
+console.log('=== Browser Workspace Overview ===\\n');
+
+if (traceSummary) {
+  var t = traceSummary.timing || traceSummary;
+  console.log('URL: ' + (traceSummary.url || '(unknown)'));
+  console.log('Page load: ' + Math.round(t.loadComplete || 0) + 'ms | FCP: ' + Math.round(t.firstContentfulPaint || 0) + 'ms | LCP: ' + Math.round(t.largestContentfulPaint || 0) + 'ms | TBT: ' + Math.round(t.totalBlockingTime || 0) + 'ms');
+  console.log('Requests: ' + (traceSummary.requestCount || 0) + ' | Transfer: ' + ((traceSummary.totalTransferSize || 0) / 1024).toFixed(1) + ' KB | Decoded: ' + ((traceSummary.totalDecodedSize || 0) / 1024).toFixed(1) + ' KB');
+  if (traceSummary.renderBlockingResources && traceSummary.renderBlockingResources.length > 0) {
+    console.log('Render-blocking: ' + traceSummary.renderBlockingResources.length + ' resources');
+  }
+  console.log();
+}
+
+if (heapSummary) {
+  var meta = heapSummary.metadata || {};
+  console.log('=== Heap Summary ===\\n');
+  console.log('Total heap: ' + ((meta.totalSize || 0) / 1024 / 1024).toFixed(2) + ' MB | Nodes: ' + (meta.nodeCount || 0) + ' | Edges: ' + (meta.edgeCount || 0));
+  var detached = heapSummary.detachedNodes || heapSummary.detachedDomNodes;
+  if (detached) {
+    var dCount = detached.count || (Array.isArray(detached) ? detached.length : 0);
+    var dSize = detached.totalSize || 0;
+    console.log('Detached DOM nodes: ' + dCount + (dSize ? ' (' + (dSize / 1024).toFixed(1) + ' KB)' : ''));
+  }
+  var closures = heapSummary.closureStats;
+  if (closures && closures.count) {
+    console.log('Closures: ' + closures.count + ' (' + ((closures.totalSize || 0) / 1024).toFixed(1) + ' KB)');
+  }
+  console.log();
+}
+
+if (rtSummary) {
+  console.log('=== Runtime Trace Summary ===\\n');
+  console.log('Trace duration: ' + Math.round(rtSummary.traceDuration || 0) + 'ms');
+  console.log('Blocking functions: ' + (rtSummary.blockingFunctionCount || 0));
+  console.log('Listener imbalances: ' + (rtSummary.listenerImbalances || 0));
+  console.log('GC pauses: ' + (rtSummary.gcPauseCount || 0) + ' (' + Math.round(rtSummary.gcTotalDuration || 0) + 'ms total)');
+  if (rtSummary.frameBreakdown) {
+    var fb = rtSummary.frameBreakdown;
+    console.log('Frame breakdown: scripting=' + Math.round(fb.scripting || 0) + 'ms  layout=' + Math.round(fb.layout || 0) + 'ms  paint=' + Math.round(fb.paint || 0) + 'ms  gc=' + Math.round(fb.gc || 0) + 'ms');
+  }
+  if (rtSummary.frequentEventTypes && rtSummary.frequentEventTypes.length > 0) {
+    console.log('Frequent events: ' + rtSummary.frequentEventTypes.join(', '));
+  }
+  console.log();
+}
+
+if (Array.isArray(blockingFunctions) && blockingFunctions.length > 0) {
+  console.log('=== Top Blocking Functions ===\\n');
+  var top = blockingFunctions.slice(0, 10);
+  for (var i = 0; i < top.length; i++) {
+    var fn = top[i];
+    console.log('  [' + (fn.duration || 0) + 'ms] ' + (fn.functionName || '(anonymous)') + ' @ ' + (fn.scriptUrl || 'unknown') + ':' + (fn.lineNumber || '?'));
+  }
+  if (blockingFunctions.length > 10) {
+    console.log('  ... and ' + (blockingFunctions.length - 10) + ' more');
+  }
+  console.log();
+}
+
+if (Array.isArray(eventListeners) && eventListeners.length > 0) {
+  var imbalanced = eventListeners.filter(function (l) {
+    return (l.addCount || 0) > (l.removeCount || 0) + 2;
+  });
+  if (imbalanced.length > 0) {
+    console.log('=== Listener Imbalances (adds >> removes) ===\\n');
+    for (var i = 0; i < imbalanced.length; i++) {
+      var l = imbalanced[i];
+      console.log('  ' + l.eventType + ' on ' + (l.targetType || '?') + '  adds=' + l.addCount + '  removes=' + (l.removeCount || 0) + '  active=' + (l.activeCount || 0));
+    }
+    console.log();
+  }
+}
+
+if (traceSummary && traceSummary.renderBlockingResources && traceSummary.renderBlockingResources.length > 0) {
+  console.log('=== Render-Blocking Resources ===\\n');
+  var rbs = traceSummary.renderBlockingResources;
+  for (var i = 0; i < rbs.length; i++) {
+    var r = rbs[i];
+    console.log('  [' + (r.type || '?') + '] ' + (r.url || '?'));
+    console.log('    Size: ' + ((r.size || 0) / 1024).toFixed(1) + ' KB | Duration: ' + Math.round(r.duration || 0) + 'ms' + (r.path ? ' | File: ' + r.path : ''));
+  }
+  console.log();
+}
+
+if (Array.isArray(waterfall)) {
+  var large = waterfall.filter(function (r) {
+    return (r.size || 0) > 100000;
+  });
+  if (large.length > 0) {
+    large.sort(function (a, b) { return (b.size || 0) - (a.size || 0); });
+    console.log('=== Large Resources (>100KB) ===\\n');
+    for (var i = 0; i < Math.min(10, large.length); i++) {
+      var r = large[i];
+      console.log('  [' + (r.type || '?') + '] ' + ((r.size || 0) / 1024).toFixed(1) + 'KB  ' + (r.url || '?'));
+      if (r.path) console.log('    File: ' + r.path);
+    }
+    console.log();
+  }
+}
+
+console.log('=== Available Files ===\\n');
+var dirs = ['scripts', 'styles', 'html', 'other'];
+for (var d = 0; d < dirs.length; d++) {
+  try {
+    var files = fs.readdirSync(dirs[d]);
+    if (files.length > 0) {
+      for (var i = 0; i < files.length; i++) {
+        var full = dirs[d] + '/' + files[i];
+        try {
+          var stat = fs.statSync(full);
+          if (stat.isFile()) console.log('  ' + full + '  (' + (stat.size / 1024).toFixed(1) + ' KB)');
+        } catch (_) {}
+      }
+    }
+  } catch (_) {}
+}
+console.log();
+`;
+var ANALYZE_BLOCKERS_JS = `'use strict';
+var fs = require('fs');
+
+var threshold = 50;
+var args = process.argv.slice(2);
+for (var i = 0; i < args.length; i++) {
+  if (args[i] === '--threshold' && args[i + 1]) {
+    threshold = parseInt(args[i + 1], 10);
+    if (isNaN(threshold)) threshold = 50;
+  }
+}
+
+var data;
+try {
+  data = JSON.parse(fs.readFileSync('trace/runtime/blocking-functions.json', 'utf8'));
+} catch (e) {
+  console.log('Could not read trace/runtime/blocking-functions.json:', e.message);
+  process.exit(0);
+}
+
+if (!Array.isArray(data)) {
+  console.log('Expected an array in blocking-functions.json');
+  process.exit(0);
+}
+
+var blockers = data.filter(function (fn) { return fn.duration >= threshold; });
+blockers.sort(function (a, b) { return b.duration - a.duration; });
+
+if (blockers.length === 0) {
+  console.log('No blocking functions found above ' + threshold + 'ms threshold.');
+  process.exit(0);
+}
+
+function workspacePath(url) {
+  if (!url) return '';
+  var parts = url.split('/');
+  var filename = parts[parts.length - 1];
+  if (!filename) return url;
+  return 'scripts/' + filename;
+}
+
+var blockerNames = {};
+blockers.forEach(function (fn) {
+  blockerNames[fn.functionName] = true;
+});
+
+console.log('=== Blocking Functions (>=' + threshold + 'ms) ===');
+console.log('Found ' + blockers.length + ' blocking function(s)\\n');
+
+blockers.forEach(function (fn, idx) {
+  var wsPath = workspacePath(fn.scriptUrl);
+  console.log((idx + 1) + '. [' + fn.duration + 'ms] ' + (fn.functionName || '(anonymous)') +
+    ' @ ' + (fn.scriptUrl || 'unknown') + ':' + (fn.lineNumber || '?'));
+  if (wsPath) {
+    console.log('   Workspace: ' + wsPath);
+  }
+
+  if (fn.callStack && fn.callStack.length > 0) {
+    console.log('   Call stack:');
+    fn.callStack.forEach(function (caller) {
+      console.log('     <- ' + (caller.functionName || '(anonymous)') +
+        ' @ ' + (caller.scriptUrl || 'unknown') + ':' + (caller.lineNumber || '?'));
+    });
+  }
+
+  if (fn.callStack && fn.callStack.length > 0) {
+    var compounds = fn.callStack.filter(function (caller) {
+      return blockerNames[caller.functionName];
+    });
+    if (compounds.length > 0) {
+      console.log('   ⚠ Compound blocker — calls into:');
+      compounds.forEach(function (c) {
+        console.log('     → ' + c.functionName);
+      });
+    }
+  }
+
+  console.log('');
+});
+`;
+var ANALYZE_WATERFALL_JS = `'use strict';
+var fs = require('fs');
+
+var waterfall;
+try {
+  waterfall = JSON.parse(fs.readFileSync('trace/network-waterfall.json', 'utf8'));
+} catch (e) {
+  console.log('Could not read trace/network-waterfall.json:', e.message);
+  process.exit(0);
+}
+
+var summary = null;
+try {
+  summary = JSON.parse(fs.readFileSync('trace/summary.json', 'utf8'));
+} catch (e) {
+  // summary is optional
+}
+
+if (!Array.isArray(waterfall)) {
+  console.log('Expected an array in network-waterfall.json');
+  process.exit(0);
+}
+
+function workspacePath(url) {
+  if (!url) return '';
+  var parts = url.split('/');
+  var filename = parts[parts.length - 1];
+  if (!filename) return url;
+  var qIdx = filename.indexOf('?');
+  if (qIdx > -1) filename = filename.substring(0, qIdx);
+  return 'scripts/' + filename;
+}
+
+function toKB(bytes) {
+  return (bytes / 1024).toFixed(1) + ' KB';
+}
+
+// 1. Render-blocking resources
+var renderBlocking = waterfall.filter(function (r) { return r.isRenderBlocking; });
+console.log('=== Render-Blocking Resources ===');
+if (renderBlocking.length === 0) {
+  console.log('None found.\\n');
+} else {
+  console.log('Found ' + renderBlocking.length + ' render-blocking resource(s)\\n');
+  renderBlocking.forEach(function (r) {
+    console.log('  ' + (r.type || 'unknown') + ': ' + (r.url || 'unknown'));
+    console.log('    Size: ' + toKB(r.size || r.encodedSize || 0) +
+      ' | Duration: ' + ((r.duration || 0).toFixed(1)) + 'ms');
+    console.log('    Workspace: ' + workspacePath(r.url));
+    console.log('');
+  });
+}
+
+// 2. Large scripts (>100KB)
+var largeScripts = waterfall.filter(function (r) {
+  return r.type === 'Script' && (r.size || r.decodedSize || 0) > 100000;
+});
+console.log('=== Large Scripts (>100KB) ===');
+if (largeScripts.length === 0) {
+  console.log('None found.\\n');
+} else {
+  largeScripts.sort(function (a, b) {
+    return (b.size || b.decodedSize || 0) - (a.size || a.decodedSize || 0);
+  });
+  console.log('Found ' + largeScripts.length + ' large script(s)\\n');
+  largeScripts.forEach(function (r) {
+    console.log('  ' + (r.url || 'unknown'));
+    console.log('    Size: ' + toKB(r.size || r.decodedSize || 0) +
+      ' | Duration: ' + ((r.duration || 0).toFixed(1)) + 'ms');
+    console.log('    Workspace: ' + workspacePath(r.url));
+    console.log('');
+  });
+}
+
+// 3. Sequential chains
+var scriptAndStyle = waterfall.filter(function (r) {
+  return r.type === 'Script' || r.type === 'Stylesheet';
+});
+scriptAndStyle.sort(function (a, b) {
+  return (a.startTime || 0) - (b.startTime || 0);
+});
+
+var chains = [];
+for (var i = 0; i < scriptAndStyle.length - 1; i++) {
+  var a = scriptAndStyle[i];
+  var aEnd = (a.startTime || 0) + (a.duration || 0);
+  for (var j = i + 1; j < scriptAndStyle.length; j++) {
+    var b = scriptAndStyle[j];
+    if ((b.startTime || 0) >= aEnd) {
+      var chainDuration = (b.startTime || 0) + (b.duration || 0) - (a.startTime || 0);
+      if (chainDuration > 200) {
+        chains.push({ a: a, b: b, duration: chainDuration });
+      }
+      break;
+    }
+  }
+}
+
+console.log('=== Sequential Chains (could be parallelized) ===');
+if (chains.length === 0) {
+  console.log('None found.\\n');
+} else {
+  console.log('Found ' + chains.length + ' sequential chain(s)\\n');
+  chains.forEach(function (c) {
+    console.log('  ' + (c.a.url || 'unknown') + ' → ' + (c.b.url || 'unknown'));
+    console.log('    Chain duration: ' + c.duration.toFixed(1) + 'ms');
+    console.log('');
+  });
+}
+
+// 4. Summary render-blocking info
+if (summary && summary.renderBlockingResources) {
+  console.log('=== Summary: Render-Blocking Resources ===');
+  var rbs = summary.renderBlockingResources;
+  if (Array.isArray(rbs)) {
+    rbs.forEach(function (r) {
+      console.log('  ' + (r.url || JSON.stringify(r)));
+    });
+  } else {
+    console.log('  ' + JSON.stringify(rbs, null, 2));
+  }
+  console.log('');
+}
+`;
+var ANALYZE_HEAP_JS = `'use strict';
+var fs = require('fs');
+
+var data;
+try {
+  data = JSON.parse(fs.readFileSync('heap/summary.json', 'utf8'));
+} catch (e) {
+  console.log('Could not read heap/summary.json:', e.message);
+  process.exit(0);
+}
+
+function retainerChain(retainerPath) {
+  if (!Array.isArray(retainerPath)) return '';
+  return retainerPath.map(function (r) {
+    return r.name || r.className || '(unknown)';
+  }).join(' ← ');
+}
+
+function toKB(bytes) {
+  return (bytes / 1024).toFixed(1) + ' KB';
+}
+
+// 1. Detached DOM nodes
+console.log('=== Detached DOM Nodes ===');
+var detached = data.detachedDomNodes || data.detachedNodes || [];
+if (!Array.isArray(detached) || detached.length === 0) {
+  console.log('None found.\\n');
+} else {
+  var totalSize = detached.reduce(function (sum, n) {
+    return sum + (n.retainedSize || n.selfSize || 0);
+  }, 0);
+  console.log('Count: ' + detached.length + ' | Total retained size: ' + toKB(totalSize) + '\\n');
+  detached.forEach(function (node) {
+    console.log('  ' + (node.name || node.className || '(node)'));
+    console.log('    Retained: ' + toKB(node.retainedSize || 0) +
+      ' | Self: ' + toKB(node.selfSize || 0));
+    if (node.retainerPath) {
+      console.log('    Retainer path: ' + retainerChain(node.retainerPath));
+    }
+    if (node.scriptUrl) {
+      console.log('    ➜ Read: ' + node.scriptUrl);
+    }
+    console.log('');
+  });
+}
+
+// 2. Top 10 largest retained objects
+console.log('=== Top 10 Largest Retained Objects ===');
+var objects = data.topRetainedObjects || data.largestObjects || [];
+if (!Array.isArray(objects) || objects.length === 0) {
+  console.log('None found.\\n');
+} else {
+  var top10 = objects.slice(0, 10);
+  top10.forEach(function (obj, idx) {
+    console.log((idx + 1) + '. ' + (obj.name || '(unknown)') + ' [' + (obj.type || obj.className || '?') + ']');
+    console.log('   Self: ' + toKB(obj.selfSize || 0) + ' | Retained: ' + toKB(obj.retainedSize || 0));
+    if (obj.retainerPath) {
+      console.log('   Retainer path: ' + retainerChain(obj.retainerPath));
+    }
+    if (obj.scriptUrl) {
+      console.log('   ➜ Read: ' + obj.scriptUrl);
+    }
+    console.log('');
+  });
+}
+
+// 3. Constructor hotspots
+console.log('=== Constructor Hotspots (Top 10 by instance count) ===');
+var constructors = data.constructorStats || [];
+if (!Array.isArray(constructors) || constructors.length === 0) {
+  console.log('None found.\\n');
+} else {
+  var sorted = constructors.slice().sort(function (a, b) {
+    return (b.instanceCount || b.count || 0) - (a.instanceCount || a.count || 0);
+  });
+  sorted.slice(0, 10).forEach(function (c, idx) {
+    console.log((idx + 1) + '. ' + (c.name || c.constructor || '(unknown)') +
+      ' — ' + (c.instanceCount || c.count || 0) + ' instances' +
+      ' | Total size: ' + toKB(c.totalSize || c.retainedSize || 0));
+  });
+  console.log('');
+}
+
+// 4. Top closures
+console.log('=== Top Closures by Context Size ===');
+var closureStats = data.closureStats || {};
+var topClosures = closureStats.topClosures || [];
+if (!Array.isArray(topClosures) || topClosures.length === 0) {
+  console.log('None found.\\n');
+} else {
+  topClosures.slice(0, 10).forEach(function (cl, idx) {
+    console.log((idx + 1) + '. ' + (cl.name || cl.functionName || '(anonymous)') +
+      ' — context: ' + toKB(cl.contextSize || 0) +
+      ' | retained: ' + toKB(cl.retainedSize || 0));
+    if (cl.scriptUrl) {
+      console.log('   ➜ Read: ' + cl.scriptUrl);
+    }
+  });
+  console.log('');
+}
+`;
+var FIND_PATTERNS_JS = `'use strict';
+var fs = require('fs');
+
+var onlyPattern = null;
+var args = process.argv.slice(2);
+for (var i = 0; i < args.length; i++) {
+  if (args[i] === '--pattern' && args[i + 1]) {
+    onlyPattern = args[i + 1];
+  }
+}
+
+function normalizePath(p) {
+  return p.startsWith('/') ? p.slice(1) : p;
+}
+
+var filePaths = [];
+
+try {
+  var manifest = JSON.parse(fs.readFileSync('trace/asset-manifest.json', 'utf8'));
+  if (Array.isArray(manifest)) {
+    manifest.forEach(function (entry) {
+      var p = entry.storedPath || entry.path;
+      if (p) filePaths.push(normalizePath(p));
+    });
+  } else if (manifest && typeof manifest === 'object') {
+    Object.keys(manifest).forEach(function (key) {
+      var entry = manifest[key];
+      var p = (typeof entry === 'string') ? entry : (entry && (entry.storedPath || entry.path));
+      if (p) filePaths.push(normalizePath(p));
+    });
+  }
+} catch (e) {
+  // manifest not available
+}
+
+var extraPaths = ['html/document.html'];
+extraPaths.forEach(function (p) {
+  if (filePaths.indexOf(p) === -1) {
+    try {
+      fs.accessSync(p);
+      filePaths.push(p);
+    } catch (e) {
+      // not available
+    }
+  }
+});
+
+function readFile(p) {
+  try {
+    return fs.readFileSync(p, 'utf8');
+  } catch (e) {
+    return null;
+  }
+}
+
+var patterns = {
+  addEventListener: {
+    test: function (line) {
+      if (!/addEventListener/.test(line)) return false;
+      if (/\\b(scroll|touchstart|touchmove|wheel)\\b/.test(line) && !/passive\\s*:\\s*true/.test(line)) {
+        return true;
+      }
+      return false;
+    },
+    label: 'addEventListener without passive:true for scroll/touch/wheel'
+  },
+  missingDelegation: {
+    test: function (line, allLines, idx) {
+      if (!/querySelectorAll/.test(line)) return false;
+      var window = allLines.slice(idx, Math.min(idx + 5, allLines.length)).join(' ');
+      return /querySelectorAll/.test(window) && /forEach/.test(window) && /addEventListener/.test(window);
+    },
+    label: 'querySelectorAll+forEach+addEventListener (consider event delegation)'
+  },
+  syncXHR: {
+    test: function (line) {
+      return /XMLHttpRequest/.test(line) && /\\.open\\(/.test(line) && /,\\s*false\\s*[),]/.test(line);
+    },
+    label: 'Synchronous XMLHttpRequest'
+  },
+  documentWrite: {
+    test: function (line) {
+      return /document\\.write\\s*\\(/.test(line);
+    },
+    label: 'document.write() blocks parsing'
+  },
+  cssImport: {
+    test: function (line) {
+      return /@import\\b/.test(line);
+    },
+    label: 'CSS @import creates sequential loading'
+  },
+  imgDimensions: {
+    test: function (line) {
+      if (!/<img\\b/i.test(line)) return false;
+      var hasWidth = /\\bwidth\\s*=/.test(line);
+      var hasHeight = /\\bheight\\s*=/.test(line);
+      return !hasWidth || !hasHeight;
+    },
+    label: '<img> without width/height causes layout shift'
+  }
+};
+
+var patternKeys = Object.keys(patterns);
+if (onlyPattern) {
+  if (!patterns[onlyPattern]) {
+    console.log('Unknown pattern: ' + onlyPattern);
+    console.log('Available: ' + patternKeys.join(', '));
+    process.exit(0);
+  }
+  patternKeys = [onlyPattern];
+}
+
+var results = [];
+
+filePaths.forEach(function (filePath) {
+  var content = readFile(filePath);
+  if (!content) return;
+  var lines = content.split('\\n');
+  lines.forEach(function (line, idx) {
+    patternKeys.forEach(function (key) {
+      if (patterns[key].test(line, lines, idx)) {
+        results.push({
+          path: filePath,
+          lineNumber: idx + 1,
+          pattern: key,
+          label: patterns[key].label,
+          line: line.trim()
+        });
+      }
+    });
+  });
+});
+
+if (results.length === 0) {
+  console.log('No performance anti-patterns found.');
+  process.exit(0);
+}
+
+console.log('=== Performance Anti-Patterns ===');
+console.log('Found ' + results.length + ' issue(s)\\n');
+results.forEach(function (r) {
+  console.log(r.path + ':' + r.lineNumber + ': [' + r.pattern + '] ' + r.line);
+});
+`;
+var BROWSER_ANALYSIS_SKILL_FILES = {
+  "skills/browser-analysis/SKILL.md": SKILL_MD2,
+  "skills/browser-analysis/helpers/analyze-browser-workspace.js": ANALYZE_BROWSER_WORKSPACE_JS,
+  "skills/browser-analysis/helpers/analyze-blockers.js": ANALYZE_BLOCKERS_JS,
+  "skills/browser-analysis/helpers/analyze-waterfall.js": ANALYZE_WATERFALL_JS,
+  "skills/browser-analysis/helpers/analyze-heap.js": ANALYZE_HEAP_JS,
+  "skills/browser-analysis/helpers/find-patterns.js": FIND_PATTERNS_JS
+};
 // ../utils/src/output/terminal.ts
 import pc2 from "picocolors";
 import ora from "ora";
@@ -971,7 +2092,7 @@ function formatBytes(bytes) {
   return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
 }
 // ../utils/src/output/report.ts
-import { writeFileSync as writeFileSync2 } from "node:fs";
+import { writeFileSync } from "node:fs";
 var SEVERITY_EMOJI = {
   critical: "\uD83D\uDD34",
   warning: "\uD83D\uDFE1",
@@ -1004,7 +2125,7 @@ var CATEGORY_LABELS2 = {
 };
 function writeReport(outputPath, options) {
   const md = generateMarkdown(options);
-  writeFileSync2(outputPath, md, "utf-8");
+  writeFileSync(outputPath, md, "utf-8");
   return outputPath;
 }
 function generateMarkdown(options) {
@@ -1113,27 +2234,30 @@ import { createDeepAgent } from "deepagents";
 import { toolStrategy } from "langchain";
 
 // src/analysis/prompts/shared.ts
-var BROWSER_TOOL_CALL_STRATEGY = `## CRITICAL: Tool call strategy — data first, source selectively
+var BROWSER_TOOL_CALL_STRATEGY = `## CRITICAL: Tool call strategy — scripts first, source selectively
+
+Your FIRST turn MUST run analysis scripts against the data files (JSON) to
+extract a concise summary of issues. Use the pre-built helper scripts in
+skills/browser-analysis/helpers/ or write your own using the data-scripting
+skill. Do NOT read data JSON files directly with read_file.
 
-Your FIRST turn MUST contain read_file calls ONLY for the data files (JSON)
-listed under "Data files" in "FILES IN THIS WORKSPACE" above. Batch them
-into ONE turn. Do NOT read any source files in your first turn.
+After your analysis scripts identify specific issues, read at most 1-3
+source files that are directly implicated. Derive paths from script URLs
+in the data (e.g. a URL ending in "abc123.js" → scripts/abc123.js).
 
-After analyzing the data, read at most 1-3 source files that are directly
-implicated by the issues you found. Derive paths from script URLs in the data
-(e.g. a URL ending in "abc123.js" → /scripts/abc123.js). If no source file
-is implicated, skip reading source files entirely and report findings from
-the data alone.
+PREFERRED actions:
+- execute_command with pre-built helper scripts or custom Node.js scripts
+- read_file for source code files you need to see verbatim
 
 FORBIDDEN actions:
 - ls — NEVER call ls.
 - glob — NEVER call glob.
-- Reading ALL source files — only read the specific ones the data points to.
-- Reading source files in the first turn — always read data first.
+- read_file on data JSON files — use scripts to extract what you need.
+- Reading ALL source files — only read the specific ones your scripts point to.
 - Reading more than 3 source files — focus on the most impactful issues.`;
 var MINIFIED_SOURCE_HANDLING = `## Handling minified / compiled source files
 
-The JavaScript files in /scripts/ are captured from a PRODUCTION page. They are
+The JavaScript files in scripts/ are captured from a PRODUCTION page. They are
 almost always minified, bundled, or compiled (e.g. by webpack, Vite, Turbopack).
 Signs of compiled code: single very long lines, mangled 1-2 character variable
 names, no whitespace or comments.
@@ -1181,11 +2305,11 @@ critical. Even shorter blocking calls prevent the main thread from processing
 user interactions and paint updates.`;
 var CROSS_REFERENCING = `## Cross-referencing data
 
-- When a script appears in BOTH /trace/runtime/blocking-functions.json (CPU)
-  AND /heap/summary.json (memory), mention both dimensions in the finding.
-- Check /trace/runtime/event-listeners.json for listener imbalances and
-  cross-reference with the actual addEventListener calls in /scripts/.
-- Use /trace/network-waterfall.json to identify sequential chains, then read
+- When a script appears in BOTH trace/runtime/blocking-functions.json (CPU)
+  AND heap/summary.json (memory), mention both dimensions in the finding.
+- Check trace/runtime/event-listeners.json for listener imbalances and
+  cross-reference with the actual addEventListener calls in scripts/.
+- Use trace/network-waterfall.json to identify sequential chains, then read
   the initiating script to confirm the dependency.
 - When GC pauses are significant, cross-reference with heap data to identify
   which constructors or allocation patterns are responsible.`;
@@ -1222,9 +2346,7 @@ document.body.removeChild(el);
 // 'el' still holds a reference → detached DOM node
 \`\`\`
 
-**How to detect:** Read /heap/summary.json and check the \`detachedNodes\` section.
-For each detached node, search the source files for references to that node type
-or constructor name.
+**How to detect:** Run \`execute_command: node skills/browser-analysis/helpers/analyze-heap.js\` to get a summary of heap issues including detached nodes with retainer paths. Then read ONLY the source files referenced in the retainer paths to verify root causes.
 
 ### 2. Large Retained Objects
 
@@ -1240,10 +2362,7 @@ class DataStore {
 }
 \`\`\`
 
-**How to detect:** Read /heap/summary.json and check \`largestObjects\`. Focus on
-objects where \`retainedSize\` is significantly larger than \`selfSize\` — they are
-roots of large object trees. Cross-reference with \`retainerPath\` to understand
-what keeps them alive.
+**How to detect:** The analyze-heap.js script outputs the top 10 largest retained objects. Review the retainer paths and read the implicated source files.
 
 ### 3. Constructor Hotspots
 
@@ -1260,8 +2379,7 @@ function processItems(items) {
 }
 \`\`\`
 
-**How to detect:** Read \`constructorStats\` in the heap summary. Focus on types
-with unusually high instance counts or total size.
+**How to detect:** The analyze-heap.js script outputs constructor hotspots. Focus on types with unusually high instance counts.
 
 ### 4. Closure Leaks
 
@@ -1278,32 +2396,27 @@ function setupHandler(response) {
 }
 \`\`\`
 
-**How to detect:** Read \`closureStats\` in the heap summary. For closures with
-large retained sizes, search the source files for the function patterns and
-check what variables they capture.
+**How to detect:** The analyze-heap.js script outputs top closures by retained size. Read the implicated source files to check what variables they capture.
 
 ### 5. Unbounded Caches/Maps
 
 Data structures that grow monotonically without eviction, TTL, or size limits.
 
-**How to detect:** Read source files and look for Maps, Sets, arrays, or plain
-objects used as stores where items are added but never removed.
+**How to detect:** After identifying suspicious objects from the heap analysis script output, read the relevant source files and look for Maps, Sets, arrays used as stores where items are added but never removed.
 
 ## Your workflow
 
-1. In your FIRST turn, call read_file for /heap/summary.json ONLY.
-   Do NOT use ls or glob. Do NOT read any source files yet.
-2. From the heap summary, identify:
-   - Detached DOM nodes (count and types)
-   - Top 10 largest retained objects
-   - Constructor types with high instance counts
-   - Closures with large retained sizes
-3. For issues that reference script URLs, derive the workspace path
-   (e.g. a script URL ending in "abc123.js" maps to /scripts/abc123.js).
-   Read ONLY the 1-3 source files directly implicated — do NOT read all
-   scripts. Source files are at /scripts/*.js, /styles/*.css, /html/.
-4. Cross-reference with source code to find the root cause and provide
-   before/after code with a concrete fix.
+1. In your FIRST turn, run BOTH of these:
+   a. Run the workspace overview:
+      execute_command: node skills/browser-analysis/helpers/analyze-browser-workspace.js
+   b. Run the detailed heap analysis:
+      execute_command: node skills/browser-analysis/helpers/analyze-heap.js
+   Do NOT use ls, glob, or read_file on heap/summary.json directly.
+2. From the script outputs, identify issues and the script URLs that need verification.
+3. Derive workspace paths from script URLs (e.g. URL ending in "abc123.js" → scripts/abc123.js).
+   Read ONLY the 1-3 source files directly implicated — do NOT read all scripts.
+4. Cross-reference with source code to find the root cause and provide before/after code.
+5. For custom queries, use the data-scripting skill to write targeted scripts.
 
 ### CRITICAL: Report EVERY distinct issue
 
@@ -1349,10 +2462,7 @@ Scripts in \`<head>\` without \`async\` or \`defer\` that block first paint.
 </head>
 \`\`\`
 
-**How to detect:** Read /trace/summary.json for \`renderBlockingResources\`. For each
-render-blocking script, read the actual source file (from the \`path\` field) and judge
-whether it MUST be synchronous (e.g., it modifies the DOM before paint) or can safely
-be deferred.
+**How to detect:** Run \`execute_command: node skills/browser-analysis/helpers/analyze-waterfall.js\` to get a summary of render-blocking resources, large bundles, and sequential chains. For each render-blocking script, read the actual source file and judge whether it MUST be synchronous or can safely be deferred.
 
 ### 2. Render-Blocking CSS
 
@@ -1367,8 +2477,7 @@ Large stylesheets that block first contentful paint.
 <link rel="stylesheet" href="/styles/all.css" media="print" onload="this.media='all'">
 \`\`\`
 
-**How to detect:** Check render-blocking resources of type "Stylesheet" in the trace
-summary. Large stylesheets (>50KB) that block FCP are prime candidates for splitting.
+**How to detect:** The analyze-waterfall.js script flags render-blocking stylesheets. Large stylesheets (>50KB) that block FCP are prime candidates for splitting.
 
 ### 3. Large Bundles (>100KB)
 
@@ -1383,8 +2492,7 @@ const Chart = lazy(() => import('./components/Chart'));
 const DataGrid = lazy(() => import('./components/DataGrid'));
 \`\`\`
 
-**How to detect:** Read /trace/network-waterfall.json and identify scripts >100KB.
-Read their source to find imports or code that could be deferred.
+**How to detect:** The analyze-waterfall.js script identifies bundles >100KB. Read their source to find imports or code that could be deferred.
 
 ### 4. Sequential Waterfalls
 
@@ -1398,34 +2506,27 @@ Resources loaded sequentially that could be parallelised or preloaded.
 <link rel="preload" href="/fonts/body.woff2" as="font" type="font/woff2" crossorigin>
 \`\`\`
 
-**How to detect:** Read /trace/network-waterfall.json sorted by startTime. Look for
-chains where Resource B starts AFTER Resource A finishes, and both are needed for
-initial render. Calculate the potential savings from parallelisation.
+**How to detect:** The analyze-waterfall.js script detects sequential chains where Resource B starts AFTER Resource A finishes. Review the chains and calculate the potential savings from parallelisation.
 
 ### 5. Uncompressed or Poorly Cached Resources
 
 Assets served without compression or with missing cache headers.
 
-**How to detect:** Check the network waterfall for resources where \`encodedSize\` is
-close to \`decodedSize\` (no compression), or where large assets have no caching.
+**How to detect:** The analyze-waterfall.js script flags uncompressed resources where \`encodedSize\` is close to \`decodedSize\`, and large assets with no caching.
 
 ## Your workflow
 
-1. In your FIRST turn, call read_file for these data files in ONE batch:
-   - /trace/summary.json (PRIMARY — timing + render-blocking resources)
-   - /trace/network-waterfall.json (request timing and sizes)
-   - /trace/asset-manifest.json (index of stored assets)
-   Do NOT use ls or glob. Do NOT read source files yet.
-2. From the trace summary, identify:
-   - Render-blocking resources (scripts and stylesheets)
-   - Long tasks during page load
-   - Large bundles (>100KB)
-3. From the network waterfall, identify:
-   - Sequential chains that could be parallelised
-   - Resources with high load times
-4. Read ONLY the source files flagged as problematic (render-blocking,
-   oversized, etc.) from "Available source files" above. Batch these reads.
-5. For EACH issue, verify with the source and provide before/after code
+1. In your FIRST turn, run BOTH of these:
+   a. Run the workspace overview:
+      execute_command: node skills/browser-analysis/helpers/analyze-browser-workspace.js
+   b. Run the detailed waterfall analysis:
+      execute_command: node skills/browser-analysis/helpers/analyze-waterfall.js
+   Do NOT use ls, glob, or read_file on trace JSON files directly.
+2. From the script outputs, identify render-blocking resources, large bundles,
+   and sequential chains along with their workspace paths.
+3. Read ONLY the source files flagged as problematic. Batch these reads.
+4. For EACH issue, verify with the source and provide before/after code.
+5. For deeper analysis, use the data-scripting skill to write custom scripts.
 
 ${BROWSER_TOOL_CALL_STRATEGY}
 ${VERIFICATION_RULES}
@@ -1466,9 +2567,7 @@ async function loadData() {
 }
 \`\`\`
 
-**How to detect:** Read /trace/runtime/blocking-functions.json for functions with
-duration >50ms. For each one, read the source file at the reported line number
-to understand what the function does.
+**How to detect:** Run \`execute_command: node skills/browser-analysis/helpers/analyze-blockers.js\` to get a summary of blocking functions with durations, script locations, and compound blockers. For each one, read the source file at the reported line number to understand what the function does.
 
 **IMPORTANT — Compound blockers are SEPARATE findings:**
 If function A calls function B and B blocks the main thread, report TWO findings:
@@ -1499,9 +2598,7 @@ function onRouteChange(route) {
 }
 \`\`\`
 
-**How to detect:** Read /trace/runtime/event-listeners.json for event types where
-addCount >> removeCount. Then search the source files for addEventListener calls
-for those event types.
+**How to detect:** Write a custom script using the data-scripting skill to query trace/runtime/event-listeners.json for event types where addCount >> removeCount. Then search the source files for addEventListener calls for those event types.
 
 ### 3. GC Pressure
 
@@ -1527,9 +2624,7 @@ function animate() {
 }
 \`\`\`
 
-**How to detect:** Read /trace/runtime/summary.json for GC pause count and total
-duration. If significant, cross-reference with /heap/summary.json to find which
-constructors are responsible. Check source files for hot loops creating objects.
+**How to detect:** Write a custom script using the data-scripting skill to query trace/runtime/summary.json for GC pause count and total duration. If significant, cross-reference with heap data to find which constructors are responsible. Check source files for hot loops creating objects.
 
 ### 4. Layout Thrashing
 
@@ -1549,7 +2644,7 @@ elements.forEach((el, i) => {
 });
 \`\`\`
 
-**How to detect:** Read /trace/runtime/raw-events.json and look for rapid
+**How to detect:** Read trace/runtime/raw-events.json and look for rapid
 alternation of Layout and scripting events. Also search source files for
 patterns that read offsetHeight/offsetWidth/getBoundingClientRect inside
 loops that also modify DOM styles.
@@ -1578,28 +2673,26 @@ window.addEventListener('scroll', () => {
 });
 \`\`\`
 
-**How to detect:** Check /trace/runtime/summary.json for \`frequentEventTypes\`.
-These are event types dispatched >10 times during the trace period. Search
-source files for their handlers and check if they use throttle/debounce/rAF.
+**How to detect:** Write a custom script using the data-scripting skill to query trace/runtime/summary.json for \`frequentEventTypes\`. These are event types dispatched >10 times during the trace period. Search source files for their handlers and check if they use throttle/debounce/rAF.
 
 ## Your workflow
 
-1. In your FIRST turn, call read_file for these data files in ONE batch:
-   - /trace/runtime/blocking-functions.json (PRIMARY — blocking functions)
-   - /trace/runtime/event-listeners.json (listener add/remove counts)
-   - /trace/runtime/frame-breakdown.json (scripting vs layout vs paint vs GC)
-   - /trace/runtime/summary.json (overview with GC stats, frequent events)
-   Do NOT use ls or glob. Do NOT read any source files yet.
-2. Analyze blocking functions: for each with duration >50ms, note the
-   scriptUrl and line number from the data.
-3. Derive workspace paths from the scriptUrl field (e.g. a script URL
-   ending in "abc123.js" maps to /scripts/abc123.js). Read ONLY the 1-3
-   source files directly implicated by blocking functions or listener
-   imbalances — do NOT read all scripts.
+1. In your FIRST turn, run BOTH of these:
+   a. Run the workspace overview:
+      execute_command: node skills/browser-analysis/helpers/analyze-browser-workspace.js
+   b. Run the detailed blocking functions analysis:
+      execute_command: node skills/browser-analysis/helpers/analyze-blockers.js
+   Do NOT use ls, glob, or read_file on trace data files directly.
+2. From the script outputs, note blocking functions, their durations, script
+   locations, and compound blockers. Also note listener imbalances and GC stats
+   from the workspace overview.
+3. Derive workspace paths from scriptUrl (e.g. URL ending in "abc123.js" →
+   scripts/abc123.js). Read ONLY the 1-3 source files directly implicated.
 4. Check for compound blockers: if function A calls blocking function B,
-   report BOTH as separate findings
-5. Check event listener imbalances and find the source code responsible
-6. Check GC stats and cross-reference with heap data if available
+   report BOTH as separate findings.
+5. For deeper listener imbalance or GC analysis, write a custom script using
+   the data-scripting skill to query trace/runtime/event-listeners.json and
+   trace/runtime/summary.json.
 
 ### CRITICAL: Report EACH pattern as a SEPARATE finding
 
@@ -1646,8 +2739,7 @@ Large \`<script>\` blocks in the HTML document that block rendering.
 </head>
 \`\`\`
 
-**How to detect:** Read /html/document.html and look for inline \`<script>\` blocks
-that are large (>20 lines or >1KB) and don't need to execute before first paint.
+**How to detect:** Run \`execute_command: node skills/browser-analysis/helpers/find-patterns.js\` to scan HTML, CSS, and JS files for known anti-patterns. Also read html/document.html to check for inline \`<script>\` blocks that are large (>20 lines or >1KB) and don't need to execute before first paint.
 
 ### 2. DOM Manipulation in Loops (Layout Thrashing)
 
@@ -1671,9 +2763,7 @@ function resizeAll(elements) {
 }
 \`\`\`
 
-**How to detect:** Search source files for loops containing both DOM reads
-(offsetWidth, offsetHeight, getBoundingClientRect, getComputedStyle) and
-DOM writes (style.*, setAttribute, classList.*).
+**How to detect:** The find-patterns.js script detects DOM read+write patterns in loops. Review the flagged files for loops containing both DOM reads (offsetWidth, offsetHeight, getBoundingClientRect, getComputedStyle) and DOM writes (style.*, setAttribute, classList.*).
 
 ### 3. Missing Event Delegation
 
@@ -1693,9 +2783,7 @@ document.querySelector('.list').addEventListener('click', (e) => {
 });
 \`\`\`
 
-**How to detect:** Search source files for querySelectorAll(...).forEach(... =>
-addEventListener...) patterns or similar loops that add the same listener type
-to many elements.
+**How to detect:** The find-patterns.js script flags querySelectorAll+forEach+addEventListener patterns. Review the flagged files for similar loops that add the same listener type to many elements.
 
 ### 4. Synchronous XMLHttpRequest or Blocking APIs
 
@@ -1712,9 +2800,7 @@ const response = await fetch('/api/data');
 const data = await response.json();
 \`\`\`
 
-**How to detect:** Search source files for \`XMLHttpRequest\` with the third
-argument set to \`false\`, or \`document.write()\`, or other deprecated
-synchronous APIs.
+**How to detect:** The find-patterns.js script flags synchronous XHR, \`document.write()\`, and other deprecated synchronous APIs.
 
 ### 5. Non-Passive Scroll/Touch Event Listeners
 
@@ -1729,9 +2815,7 @@ document.addEventListener('touchstart', handler);
 document.addEventListener('touchstart', handler, { passive: true });
 \`\`\`
 
-**How to detect:** Search source files for addEventListener calls with
-'scroll', 'touchstart', 'touchmove', or 'wheel' that don't specify
-\`{ passive: true }\` as the options argument.
+**How to detect:** The find-patterns.js script flags non-passive listeners for scroll, touchstart, touchmove, and wheel events.
 
 ### 6. CSS Issues
 
@@ -1745,11 +2829,7 @@ document.addEventListener('touchstart', handler, { passive: true });
 /* GOOD: use <link> with preconnect for external fonts */
 \`\`\`
 
-**How to detect:** Read CSS files and look for:
-- \`@import\` statements (add network round-trips vs \`<link>\`)
-- Complex selectors with many combinators
-- Large unused rule blocks
-- Missing \`will-change\` or \`contain\` for animated elements
+**How to detect:** The find-patterns.js script flags CSS \`@import\` statements and complex selectors. Also read CSS files directly to check for large unused rule blocks and missing \`will-change\` or \`contain\` for animated elements.
 
 ### 7. Missing Image Dimensions Causing Layout Shifts
 
@@ -1763,26 +2843,20 @@ Images without explicit width/height that cause Cumulative Layout Shift (CLS).
 <img src="/hero.jpg" width="1200" height="600" loading="lazy">
 \`\`\`
 
-**How to detect:** Read /html/document.html and look for \`<img>\` tags without
-\`width\` and \`height\` attributes.
+**How to detect:** The find-patterns.js script flags \`<img>\` tags without \`width\` and \`height\` attributes.
 
 ## Your workflow
 
-1. In your FIRST turn, call read_file for HTML and CSS files (listed under
-   "Data files" above) in ONE batch. Do NOT read script files yet.
-2. Check HTML for: inline \`<script>\` blocks, \`<img>\` without width/height,
-   render-blocking resource references.
-3. Check CSS for: \`@import\` statements, complex selectors, missing
-   \`will-change\`/\`contain\` for animated elements.
-4. Based on issues found in HTML/CSS, read ONLY the script files that need
-   inspection (from "Available script files" above). For example:
-   - Scripts referenced by inline patterns in HTML
-   - Scripts that the HTML loads synchronously
-   Batch these reads.
-5. Check each script for: DOM reads+writes in loops, querySelectorAll+forEach
-   +addEventListener (missing delegation), non-passive scroll/touch listeners,
-   synchronous XHR.
-6. Report EACH pattern as a separate finding with before/after code.
+1. In your FIRST turn, run BOTH of these:
+   a. Run the workspace overview:
+      execute_command: node skills/browser-analysis/helpers/analyze-browser-workspace.js
+   b. Run the pattern finder:
+      execute_command: node skills/browser-analysis/helpers/find-patterns.js
+   This searches HTML, CSS, and JS files for known anti-patterns.
+2. Also read HTML and CSS files directly (they're typically small) to check
+   for inline scripts, img without dimensions, and CSS issues.
+3. Based on issues found, read ONLY the script files that need inspection.
+4. Report EACH pattern as a separate finding with before/after code.
 
 ### CRITICAL: Be thorough but selective
 
@@ -1964,7 +3038,8 @@ function buildSubagents(ctx) {
     return {
       name,
       description,
-      systemPrompt: insertFileListIntoPrompt(prompt, fileSection)
+      systemPrompt: insertFileListIntoPrompt(prompt, fileSection),
+      skills: ["skills/data-scripting/", "skills/browser-analysis/"]
     };
   });
 }
@@ -1975,12 +3050,13 @@ async function analyze(model, backend, spinner, context, { animateProgress = tru
     systemPrompt: BROWSER_ORCHESTRATOR_PROMPT,
     backend,
     subagents,
+    skills: ["skills/"],
     responseFormat: toolStrategy(FindingsSchema)
   });
   const userMessage = context ? buildBrowserUserMessage(context) : [
     "Analyze the frontend performance data in this workspace.",
     "",
-    "Start by reading /heap/summary.json, /trace/summary.json, and /trace/runtime/summary.json",
+    "Start by reading heap/summary.json, trace/summary.json, and trace/runtime/summary.json",
     "to understand the overall picture, then explore source files to verify root causes."
   ].join(`
 `);
@@ -2822,7 +3898,9 @@ async function createWorkspace(options) {
       }
     }
   }
-  const result = createWorkspaceFromFiles(files, "zeitzeuge-browser-workspace-");
+  Object.assign(files, DATA_SCRIPTING_SKILL_FILES);
+  Object.assign(files, BROWSER_ANALYSIS_SKILL_FILES);
+  const result = await createWorkspaceFromFiles(files);
   return {
     backend: result.backend,
     cleanup: result.cleanup,