feat: initial memory debugging skill

Author: devnook

skills/memory-leak-debugging/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: memory-leak-debugging
+description: Diagnoses and resolves memory leaks in JavaScript/Node.js applications. Use when a user reports high memory usage, OOM errors, or wants to analyze heapsnapshots or run memory leak detection tools like memlab.
+---
+
+# Memory Leak Debugging
+
+This skill provides expert guidance and workflows for finding, diagnosing, and fixing memory leaks in JavaScript and Node.js applications.
+
+## Core Principles
+
+- **Prefer `memlab`:** Do NOT attempt to read raw `.heapsnapshot` files directly, as they are extremely large and will consume too many tokens. Always recommend and use `memlab` to process snapshots and identify leak traces.
+- **Isolate the Leak:** Determine if the leak is in the browser (client-side) or Node.js (server-side).
+- **Common Culprits:** Look for detached DOM nodes, unhandled closures, global variables, event listeners not being removed, and caches growing unbounded.
+
+## Workflows
+
+### 1. Using Memlab (Recommended)
+
+When users provide `.heapsnapshot` files or want to find a memory leak, use `memlab` to automatically find memory leaks.
+
+- Read [references/memlab.md](references/memlab.md) for how to use `memlab` to analyze existing heapsnapshots or run automated E2E test scenarios to find leaks.
+- Do **not** read raw `.heapsnapshot` files using `read_file` or `cat`.
+
+### 2. Identifying Common Leaks
+
+When you have found a leak trace (e.g., via `memlab` output), you must identify the root cause in the code.
+
+- Read [references/common-leaks.md](references/common-leaks.md) for examples of common memory leaks and how to fix them.
+
+### 3. Creating Memlab Scenarios
+
+To help users reproduce and test for leaks automatically, you can create a Memlab scenario file.
+
+- An example template is available at `scripts/memlab-scenario.js`.

skills/memory-leak-debugging/references/common-leaks.md

@@ -0,0 +1,33 @@
+# Common Memory Leaks
+
+When analyzing a retainer trace from `memlab`, look for these common patterns in the codebase:
+
+## 1. Detached DOM Nodes
+
+A DOM node is removed from the document tree but is still referenced by a JavaScript variable.
+
+**Fix:** Ensure variables holding DOM references are set to `null` when the node is removed, or limit their scope.
+
+## 2. Uncleared Event Listeners
+
+Event listeners attached to global objects (like `window` or `document`) or long-living objects prevent garbage collection of the objects referenced in their callbacks.
+
+**Fix:** Always call `removeEventListener` when a component unmounts or the listener is no longer needed.
+
+## 3. Unintentional Global Variables
+
+Variables declared without `var`, `let`, or `const` (in non-strict mode) or explicitly attached to `window` remain in memory forever.
+
+**Fix:** Use strict mode, properly declare variables, and avoid global state.
+
+## 4. Closures
+
+Closures can unintentionally keep references to large objects in their outer scope.
+
+**Fix:** Nullify large objects when they are no longer needed, or refactor the closure to not capture unnecessary variables.
+
+## 5. Unbounded Caches or Arrays
+
+Data structures used for caching (like objects, Arrays, or Maps) that grow without limits.
+
+**Fix:** Implement caching limits, use LRU caches, or use `WeakMap`/`WeakSet` for data associated with object lifecycles.

skills/memory-leak-debugging/references/memlab.md

@@ -0,0 +1,32 @@
+# Using Memlab
+
+[Memlab](https://facebook.github.io/memlab/) is an E2E testing and analysis framework for finding JavaScript memory leaks.
+
+## Important Rule
+
+**NEVER read raw `.heapsnapshot` files directly.** They are too large and will exceed context limits. Use `memlab` commands to analyze them instead.
+
+## Analyzing Existing Snapshots
+
+If the user provides 3 snapshots (baseline, target, final), you can use `memlab` to find leaks:
+
+```bash
+npx memlab find-leaks --baseline <path-to-baseline> --target <path-to-target> --final <path-to-final>
+```
+
+You can also parse a single snapshot to find the largest objects:
+
+```bash
+npx memlab analyze snapshot --snapshot <path-to-snapshot>
+```
+
+## Running Automated Scenarios
+
+Memlab can automatically open a browser, interact with a page, take snapshots, and find leaks.
+You need a scenario file (e.g., `scenario.js`).
+
+```bash
+npx memlab run --scenario <path-to-scenario.js>
+```
+
+Memlab will output the retainer traces for identified leaks. Use these traces to guide your search in the codebase.

skills/memory-leak-debugging/scripts/memlab-scenario.js

@@ -0,0 +1,23 @@
+// Memlab Scenario Template
+module.exports = {
+  // Required: The URL to load
+  url: () => 'http://localhost:3000',
+
+  // Required: Action to trigger the memory leak
+  action: async (page) => {
+    // Example: Click a button that causes a leak
+    await page.click('#leak-button');
+    // Wait for any animations or network requests to settle
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  },
+
+  // Required: Action to revert to the baseline state
+  back: async (page) => {
+    // Example: Click a back button or close a modal
+    await page.click('#back-button');
+    await new Promise(resolve => setTimeout(resolve, 1000));
+  },
+
+  // Optional: Function to run before taking the baseline snapshot
+  // setup: async (page) => { ... },
+};