lazycodex-ai 5.0.0-beta.9 → 5.0.0

package/packages/shared-skills/skills/data-scientist/references/execution-surfaces.md

@@ -0,0 +1,91 @@
+# Execution surfaces
+
+How to run the engines on each surface, and when to escalate between them.
+
+## Persistent kernel, JavaScript (Bun)
+
+One-time setup per machine — the bundled script installs `@duckdb/node-api` into a user-level
+cache outside any repo and prints the absolute import path (its only stdout line):
+
+```bash
+bash scripts/ensure-js-deps.sh          # run from the skill directory
+```
+
+In the kernel — top-level `require` may not exist, dynamic import always works:
+
+```js
+const { DuckDBInstance } = await import("<printed path>");
+const db = await DuckDBInstance.create(":memory:");
+const conn = await db.connect();
+const reader = await conn.runAndReadAll("SELECT category, SUM(v) AS total FROM 'data.csv' GROUP BY 1");
+reader.getRowObjects();                  // array of plain row objects
+```
+
+- The connection and any tables created live across cells — connect once per session, reuse.
+- COUNT/SUM over integer columns return BigInt; convert (`Number(x)` or `String(x)`) before
+  `JSON.stringify`, which throws on BigInt.
+- Bun builtins cover ingest gaps with zero installs: `Bun.JSONL.parse`, `Bun.JSON5.parse`,
+  `Bun.XML.parse`, `Bun.TOML.parse`, `Bun.Archive` for tarballs.
+- nodejs-polars is NOT part of this skill's toolkit: its API lags the Python release by
+  major versions (option objects that work in Python throw napi type errors). Polars work
+  belongs to the Python kernel (below).
+
+## Persistent kernel, Python (the default Python surface)
+
+duckdb, numpy, and matplotlib are typically resident — import and use them directly.
+Polars and pyarrow rarely ship with a kernel, so inject them once per session (run from the
+skill directory; the script installs on first use, then just prints the path):
+
+```python
+import subprocess, sys
+site = subprocess.run(["bash", "scripts/ensure-py-deps.sh", sys.executable],
+                      capture_output=True, text=True, check=True).stdout.strip()
+sys.path.insert(0, site)
+import polars as pl
+import pyarrow
+```
+
+- The install goes to a user cache keyed to the kernel's interpreter version; the
+  interpreter itself is never mutated (it is frequently an externally-managed system
+  Python, and mutating it breaks other tools).
+- After injection the whole Python stack is resident: `duckdb.sql(...).pl()` hands off via
+  Arrow, `duckdb.register(name, df)` goes the other way, and Polars lazy pipelines run
+  in-kernel across cells.
+- `duckdb.sql("SELECT ... FROM 'data.csv'")` queries files in place; without the injection,
+  keep results in DuckDB or fetch plain Python values (`.fetchall()`).
+- matplotlib figures render natively in kernels that display rich output; also save a PNG so
+  the artifact survives the session.
+
+## uv lane (fallback and isolation)
+
+```bash
+uv run --with duckdb --with polars --with pyarrow --with numpy python -c "<code>"
+```
+
+- Reach for it when there is no kernel, or when a heavy, crash-prone one-shot should not
+  run inside (and possibly take down) the kernel.
+- Include exactly the packages the code imports, plus pyarrow whenever `.pl()` is used.
+- Each invocation pays process spawn plus imports (roughly 0.3s warm) and re-reads its inputs —
+  fine for one-shots, wasteful for exploration loops.
+- Past a few lines, a temp file beats `-c` quoting: write the script, `uv run script.py`.
+
+## No kernel at all
+
+Same engines, one process per batch of questions:
+
+```bash
+bun -e '<the JavaScript kernel pattern above>'         # DuckDB via @duckdb/node-api
+uv run --with duckdb python -c "<sql via duckdb.sql>"  # DuckDB via Python
+uv run scripts/quick-query.py data.csv "SELECT ..."    # zero-code CLI fallback
+```
+
+## Escalation rules
+
+Start on the resident kernel. Move a step down when a concrete need appears:
+
+- polars/pyarrow missing from the kernel — inject via `ensure-py-deps.sh` (above), not a
+  uv one-shot.
+- Crash-prone or memory-hungry one-shot that should not take the kernel down — uv lane.
+- No kernel on this harness — one-shot recipes above.
+- Data lives remotely or exceeds local RAM — read `placement.md` and move the query, not
+  the data.

package/packages/shared-skills/skills/data-scientist/references/placement.md

@@ -0,0 +1,74 @@
+# Placement: where should this computation live?
+
+Decide before touching the data. Wrong placement wastes minutes (re-scanning a file queried
+ten times) or kills the machine (loading a dataset larger than RAM and swapping).
+
+## The probe (run first, once)
+
+Three facts, one cell or script:
+
+```python
+import os, shutil, subprocess, sys
+size = os.path.getsize("data.csv")            # bytes on disk
+disk_free = shutil.disk_usage(".").free       # spill headroom
+if sys.platform == "darwin":
+    ram = int(subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True).stdout)
+else:
+    ram = os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+# row estimate without loading (DuckDB streams the scan):
+# duckdb.sql("SELECT count(*) FROM 'data.csv'")
+```
+
+CSV typically expands 2-5x in memory (string columns dominate); Parquet expands less
+predictably — compressed columns can inflate 10x. Estimate the working set from the
+decompressed size of the columns the question actually touches, not the file size.
+
+## In memory — load once, iterate
+
+When the working set stays within roughly 25% of free RAM AND the session will run repeated
+queries: load once (`CREATE TABLE t AS SELECT ...` in DuckDB, or a collected DataFrame),
+then iterate. One scan up front converts every later query from a file re-scan into
+milliseconds. Prune at load time — select only the needed columns, filter obvious dross —
+so the resident table is the working set, not the raw file.
+
+## In place / streaming — single pass, or bigger than RAM
+
+- Single-pass questions: query the file directly (`FROM 'data.csv'`). Loading first is pure
+  waste.
+- Bigger than RAM, SQL-shaped: cap DuckDB and let it spill —
+
+  ```sql
+  SET memory_limit = '4GB';
+  SET temp_directory = '/tmp/duckdb_spill';
+  ```
+
+  Aggregations, sorts, and window functions run out-of-core: slower, but bounded.
+- Bigger than RAM, DataFrame-shaped: Polars streaming (`collect(engine="streaming")` on a
+  lazy plan) in the resident kernel — or a uv one-shot on kernel-less harnesses.
+- Manual chunked loops (read N rows, process, repeat) are the last resort — the engines'
+  own out-of-core paths are faster and simpler than hand-rolled chunking.
+
+## Remote, in place — move the query to the data
+
+- Files behind http(s)/S3: DuckDB's httpfs extension reads Parquet and CSV remotely with
+  projection and predicate pushdown —
+
+  ```sql
+  INSTALL httpfs; LOAD httpfs;   -- one-time per environment
+  SELECT region, SUM(amount) FROM 'https://example.com/sales.parquet'
+  WHERE sale_date >= '2026-01-01' GROUP BY region;
+  ```
+
+  Only matching row groups and referenced columns cross the network, not the file.
+- Data on another machine you can execute on (a remote worker with more RAM, a box closer
+  to the data): run the query there and return the aggregate. A group-by result is
+  kilobytes; the source is gigabytes.
+- Decision rule: result much smaller than data — move the query. Repeated local iteration
+  on one slice — move a pruned copy of that slice once, then work locally in memory.
+
+## Hardware notes
+
+- Both engines parallelize across all cores by default; leave that alone except on shared
+  machines (`SET threads = N` in DuckDB, `POLARS_MAX_THREADS` for Polars).
+- Sustained swapping is the failure mode to avoid on memory-tight machines: when the probe
+  says the working set is close to free RAM, choose streaming, not hope.

package/packages/shared-skills/skills/data-scientist/references/polars-lane.md

@@ -0,0 +1,95 @@
+# Polars lane (resident Python kernel)
+
+When the work is DataFrame-shaped, Polars is the right engine — and it runs in the resident
+Python kernel by default. Kernels rarely ship polars/pyarrow preinstalled, so inject them
+once per session; the install lands in a user cache keyed to the kernel's interpreter, and
+the interpreter itself is never mutated (run with the skill directory as cwd, or spell out
+the script's absolute path):
+
+```python
+import subprocess, sys
+site = subprocess.run(["bash", "scripts/ensure-py-deps.sh", sys.executable],
+                      capture_output=True, text=True, check=True).stdout.strip()
+sys.path.insert(0, site)
+import polars as pl
+```
+
+After this, Polars lives across cells like every other resident engine: lazy frames,
+intermediate results, and the DuckDB handoff all persist with no per-call process cost.
+
+## When Polars wins over DuckDB SQL
+
+- Expression-chain transforms: many derived columns, per-column conditional logic, string
+  pipelines — `with_columns` chains read and optimize better than nested SQL SELECTs.
+- Reshapes: `unpivot`/`pivot` beat SQL gymnastics.
+- Larger-than-RAM pipelines: the streaming engine executes lazy plans in chunks.
+- Window-heavy feature engineering with `over()`.
+
+SQL-shaped work (joins, aggregation, ad-hoc questions) stays in DuckDB; mixed pipelines hand
+off zero-copy (below) instead of forcing one engine to do everything.
+
+## Current API (1.x) — older spellings fail or warn
+
+Training data is full of the pre-1.0 API. Current names:
+
+| Use | Not |
+| --- | --- |
+| `pl.scan_csv` / `pl.scan_parquet` + `.collect()` | eager `read_*` on big files |
+| `.group_by(...)` | `.groupby(...)` |
+| `pl.len()` | `pl.count()` |
+| `.collect(engine="streaming")` | `.collect(streaming=True)` |
+| `.unpivot(...)` | `.melt(...)` |
+
+Lazy first: `scan_*` builds a plan, pushes filters and projections down to the file read, and
+executes once at `.collect()`. Eager `read_*` is for small files mutated interactively.
+
+```python
+out = (pl.scan_csv("data.csv")
+       .filter(pl.col("value") > 100)
+       .group_by("category")
+       .agg(pl.col("value").sum().alias("total"), pl.len().alias("n"))
+       .sort("total", descending=True)
+       .collect())
+```
+
+## Zero-copy handoff with DuckDB
+
+Both engines speak Arrow, so mixed pipelines pay no serialization cost — all in-kernel:
+
+```python
+import duckdb
+df = duckdb.sql("SELECT * FROM 'orders.csv' o JOIN 'items.csv' i USING (id)").pl()
+shaped = df.with_columns((pl.col("qty") * pl.col("price")).alias("rev"))
+duckdb.register("shaped", shaped)
+out = duckdb.sql("SELECT category, SUM(rev) AS total FROM shaped GROUP BY 1").pl()
+```
+
+- `.pl()` requires pyarrow — the injection above provides it; without it, it raises
+  `ModuleNotFoundError`.
+- Never `.df()`: it requires pandas (raising without it), and pandas is banned and absent.
+
+## Streaming past RAM
+
+```python
+out = (pl.scan_parquet("huge.parquet")
+       .filter(pl.col("status") == "active")
+       .group_by("region").agg(pl.len())
+       .collect(engine="streaming"))
+```
+
+Streaming executes lazy plans only — keep the plan lazy end-to-end, with no intermediate
+`.collect()` breaking it into eager pieces.
+
+## Kernel-less fallback (uv one-shot)
+
+On a harness with no persistent kernel, the same code runs as one-shots — batch several
+questions per process, since each invocation pays spawn plus imports:
+
+```bash
+uv run --with duckdb --with polars --with pyarrow python -c "
+import duckdb
+import polars as pl
+df = duckdb.sql(\"SELECT * FROM 'data.csv'\").pl()
+print(df.group_by('category').agg(pl.len()).sort('category'))
+"
+```

package/packages/shared-skills/skills/data-scientist/references/uv-setup.md

@@ -1,6 +1,6 @@
 # uv Setup — Per-Platform
 
-This skill runs every data operation through `uv run --with ...`. If `uv --version` fails, set uv up with the automated scripts or the manual commands below, then verify.
+This skill's uv lane (kernel-less harnesses, isolated one-shots) runs through `uv run --with ...`, and `scripts/ensure-py-deps.sh` uses uv as its installer. If `uv --version` fails, set uv up with the automated scripts or the manual commands below, then verify.
 
 ## Automated (recommended)
 

package/packages/shared-skills/skills/data-scientist/references/visualization.md

@@ -0,0 +1,64 @@
+# Visualization
+
+A chart exists to answer a question at a glance. Render it with matplotlib (resident in most
+Python kernels; `uv run --with matplotlib` otherwise), then look at it before delivering —
+a chart nobody inspected is not evidence.
+
+## When to chart
+
+Chart when the user asked for one, and default to charting when the answer is a shape prose
+cannot carry: a trend over time, a distribution, a comparison across many categories, a
+relationship between variables. Skip the chart when a number or a five-row table answers the
+question — decoration dilutes the answer.
+
+## Chart type follows the question
+
+| Question shape | Chart |
+| --- | --- |
+| How did X change over time? | line, datetime x-axis |
+| Which categories are biggest? | horizontal bar, sorted by value |
+| How is X distributed? | histogram (tune bin count) or box plot per group |
+| Is X related to Y? | scatter; add a trend line only when it aids the eye |
+| Composition of a whole? | stacked or 100% bar — pie only for four or fewer slices |
+| Many series over time? | small multiples over one spaghetti chart |
+
+## Quality bar — every chart
+
+- Title states the finding ("Seoul overtook Busan in March"), not the dataset name.
+- Axis labels carry units. Tick density stays readable: `fig.autofmt_xdate()` for dates,
+  rotate or abbreviate long category names.
+- Size for the medium: inline chat reads well around `figsize=(10, 6)` at default dpi;
+  documents want `dpi=150` or more at export.
+- `tight_layout()` (or `constrained_layout=True`) before saving — clipped labels are the
+  most common chart defect.
+- Few series: label lines directly, or keep the legend inside empty plot space. Many
+  series: gray the context, color only the series that answers the question.
+- The default color cycle is fine; avoid rainbow palettes and 3D. Sort categorical bars by
+  value, never alphabetically.
+
+## CJK and other non-Latin text
+
+Matplotlib's default font renders CJK as empty boxes (tofu). Set a fallback before plotting
+whenever any label or title contains CJK:
+
+```python
+import platform
+import matplotlib
+cjk = {"Darwin": "AppleGothic", "Windows": "Malgun Gothic"}.get(platform.system(), "Noto Sans CJK KR")
+matplotlib.rcParams["font.family"] = [cjk, "DejaVu Sans"]
+matplotlib.rcParams["axes.unicode_minus"] = False   # keeps the minus sign rendering
+```
+
+## Output contract
+
+1. Save a PNG next to the work: `plt.savefig(path, dpi=150, bbox_inches="tight")`.
+2. Also render inline when the surface displays rich output (kernels usually do).
+3. Report the file path together with the answer.
+
+## Visual QA — mandatory
+
+Open the produced image — kernel display, or the harness's image-reading surface — and
+check four things: labels readable and unclipped, no tofu or mojibake, nothing overlapping,
+and the chart actually shows the finding the title claims. A failed check means fix and
+re-render, not ship with a caveat. This one pass catches nearly every chart defect;
+skipping it is how tofu titles reach users.

package/packages/shared-skills/skills/data-scientist/scripts/ensure-js-deps.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Install @duckdb/node-api into a user-level cache (outside any repo) and print the
+# absolute import path as the ONLY stdout line. Idempotent: re-runs reuse the install.
+set -euo pipefail
+
+log() { printf '[ensure-js-deps] %s\n' "$*" >&2; }
+
+CACHE_DIR="${OMO_DATA_SCIENTIST_CACHE:-$HOME/.cache/omo-data-scientist}"
+IMPORT_PATH="$CACHE_DIR/node_modules/@duckdb/node-api/lib/index.js"
+
+if ! command -v bun >/dev/null 2>&1; then
+  log "bun is required (https://bun.sh); install it, or use the uv lane instead."
+  exit 1
+fi
+
+if [ ! -f "$IMPORT_PATH" ]; then
+  log "installing @duckdb/node-api into $CACHE_DIR"
+  mkdir -p "$CACHE_DIR"
+  [ -f "$CACHE_DIR/package.json" ] || printf '{"name":"omo-data-scientist-cache","private":true}\n' > "$CACHE_DIR/package.json"
+  (cd "$CACHE_DIR" && bun add @duckdb/node-api 1>&2)
+fi
+
+if [ ! -f "$IMPORT_PATH" ]; then
+  log "install finished but $IMPORT_PATH is missing; inspect $CACHE_DIR"
+  exit 1
+fi
+
+printf '%s\n' "$IMPORT_PATH"

package/packages/shared-skills/skills/data-scientist/scripts/ensure-py-deps.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Install polars + pyarrow for a given Python interpreter into a user-level cache
+# (never mutating the interpreter itself) and print the site directory as the ONLY
+# stdout line. Idempotent: re-runs reuse the install. arg1 = python executable
+# (default: python3); pass the kernel's sys.executable for kernel use.
+set -euo pipefail
+
+log() { printf '[ensure-py-deps] %s\n' "$*" >&2; }
+
+PYTHON_BIN="${1:-python3}"
+
+if ! command -v uv >/dev/null 2>&1; then
+  log "uv is required (see references/uv-setup.md); install it first."
+  exit 1
+fi
+if ! command -v "$PYTHON_BIN" >/dev/null 2>&1 && [ ! -x "$PYTHON_BIN" ]; then
+  log "python executable not found: $PYTHON_BIN"
+  exit 1
+fi
+
+TAG="$("$PYTHON_BIN" -c 'import sys; print(f"cp{sys.version_info[0]}{sys.version_info[1]}")')" \
+  || { log "not a working python interpreter: $PYTHON_BIN"; exit 1; }
+CACHE_DIR="${OMO_DATA_SCIENTIST_CACHE:-$HOME/.cache/omo-data-scientist}"
+SITE_DIR="$CACHE_DIR/py-$TAG"
+
+if [ ! -d "$SITE_DIR/polars" ] || [ ! -d "$SITE_DIR/pyarrow" ]; then
+  log "installing polars + pyarrow for $TAG into $SITE_DIR"
+  mkdir -p "$SITE_DIR"
+  uv pip install --python "$PYTHON_BIN" --target "$SITE_DIR" polars pyarrow 1>&2
+fi
+
+if [ ! -d "$SITE_DIR/polars" ]; then
+  log "install finished but $SITE_DIR/polars is missing; inspect $SITE_DIR"
+  exit 1
+fi
+
+printf '%s\n' "$SITE_DIR"

package/packages/shared-skills/skills/debugging/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging
-description: "MUST USE for any real runtime debugging across ANY language or binary — crashes, silent failures, wrong responses, stuck processes, memory leaks, async misbehavior, unexplained timing, reverse engineering. Runs a hypothesis-driven loop: form ≥3 hypotheses, investigate in parallel, after 2 failed rounds spawn Oracles from orthogonal angles, confirm root cause, lock with a failing test, fix minimally, QA by actually USING the system, scrub artifacts. The actual HOW lives in `references/` — READ THEM. Triggers: 'debug this', 'why is X not working', 'hanging', 'attach a debugger', 'reverse engineer', 'pwndbg', 'gdb', 'lldb', 'node inspect', 'pdb', 'dlv', 'delve', 'rust-gdb', 'set a breakpoint', 'context window exploded', 'why is the response empty', 'why is this happening', 'trace this bug', 'reproduce and fix', 'silent failure', 'HTTP 200 but empty', 'why did it stop', 'inspect the binary', 'playwright', 'flaky test', 'fails intermittently', 'passes in isolation', 'only fails in CI'."
+description: "Runs a hypothesis-driven debugging loop across any language or binary, escalating to orthogonal oracle angles and locking the fix with a failing test. Use for crashes, silent failures, hangs, wrong responses, memory leaks, async misbehavior, or reverse engineering."
 ---
 
 # Debugging
@@ -49,10 +49,12 @@ These are not "optional extras". They are the correct tool in their domain, and
 
 | Tool | Use when | Reference |
 |---|---|---|
-| **Playwright CLI** | Any browser-served web UI bug. Any flow that requires clicking/typing/navigating. Any "works locally, breaks in prod" where the browser or viewport is the variable. **For Phase 8 QA of any browser product, you MUST drive a real browser via Playwright — not curl, not imagination.** | 📖 **[references/tools/playwright-cli.md](references/tools/playwright-cli.md)** |
+| **omowright** | Any browser-served web UI bug. Any flow that requires clicking/typing/navigating. Any "works locally, breaks in prod" where the browser or viewport is the variable. **For Phase 8 QA of any browser product, you MUST drive a real browser through omowright — not curl, not imagination.** | 📖 **[references/tools/browser-qa.md](references/tools/browser-qa.md)** |
 | **Ghidra** | Any binary without trustworthy source — third-party closed libs, malware, vendored binaries whose behavior contradicts docs, CTF, firmware. **Use Ghidra's decompiler before `strings`/`objdump` guessing. It turns machine code into readable C.** | 📖 **[references/tools/ghidra.md](references/tools/ghidra.md)** |
 | **pwndbg** | Any native binary debugging session. It is GDB with the useful views (registers, stack, disasm, heap) always visible. **If you'd reach for plain `gdb`, reach for `pwndbg` instead — it is strictly a superset.** | 📖 **[references/tools/pwndbg.md](references/tools/pwndbg.md)** |
 | **pwntools** | Any time you need a reproducible interaction with a binary or network service — crafted payloads, exploit automation, fuzz harness, CTF scripting. | 📖 **[references/tools/pwntools.md](references/tools/pwntools.md)** |
+| **Frida** | Any running process you must instrument live without source or symbols — hook a function and print real argument values, trace calls, stub a return. Complements Ghidra: Ghidra reads the bytes, Frida watches them execute. **If Ghidra's static decompile has hit its limit, reach for Frida.** | 📖 **[references/tools/frida.md](references/tools/frida.md)** |
+| **DAP client (`dap.mjs`)** | Any time you would drive a debugger through a PTY and screen-scrape its text. Debuggers already speak the machine-readable Debug Adapter Protocol (debugpy, `dlv dap`, lldb-dap, js-debug); this bundled script drives it with bounded, monitorable output. **Prefer it over scraping `gdb`/`pdb` whenever the debugger speaks DAP.** Design modeled on oh-my-pi's `debug` tool (github.com/can1357/oh-my-pi). | 📖 **[references/tools/dap.md](references/tools/dap.md)** |
 
 **Failing to use these tools in their domain is a process failure, not a stylistic choice.** If the bug is in a browser and you did Phase 8 without Playwright, you are doing it wrong. If the bug is in a stripped binary and you read hex with `xxd`, you are doing it wrong. The references tell you how. Read them.
 
@@ -95,7 +97,7 @@ These are not phases — read them when the situation calls for them:
 <safety>
 1. **Runtime state is the only source of truth.** A hypothesis without an observed value is a guess. Do not fix guesses.
 2. **Every debug artifact is journaled before it is created.** Journal-then-modify, not modify-then-remember-maybe.
-3. **Never ship a fix without a failing-first test.** Red→green transition required, or the fix is unverified.
+3. **Never ship a fix without its reproduction.** The failing case captured BEFORE the fix, the same case passing after it, or the fix is unverified. Where the repository keeps tests for this behavior, that case is the regression test.
 4. **Never declare done on type-check/compile alone.** Types catch declaration bugs. Only running the actual user scenario catches the actual user bug.
 5. **Never ask the user a question that runtime evidence can already answer.** Escalation is for genuine ambiguity.
 6. **Never silently swallow errors while debugging.** If the system swallows errors, that is often the bug itself. Make them loud temporarily; restore at cleanup.

package/packages/shared-skills/skills/debugging/references/methodology/00-setup.md

@@ -35,6 +35,18 @@ The shape of the answers you need (commands in the runtime reference):
 | Is there an existing failing test or known repro? | Prefer amplifying an existing repro over inventing one. |
 | Are watchers (file watchers, hot reloaders, supervisors) going to restart the process mid-session? | If yes, turn them off before attaching. Restarts drop inspector connections and invalidate breakpoints. |
 
+### Output budget
+
+**Bound every inspection before you run it; unbounded output destroys the investigation's working context.**
+- Set a frame count, element count, or byte range for every query.
+- Prefer one targeted query over one broad dump: ask for the value that distinguishes hypotheses.
+- Page through more data only when the first bounded result says it is necessary; do not re-dump the whole object.
+- Treat any command whose output size you cannot predict as a command that needs a limit.
+- Before: GDB `bt` — After: GDB `bt 10` to inspect only the top ten frames.
+- Before: LLDB `memory read 0x1000` — After: `memory read 0x1000 -c 32` for a bounded byte range.
+- Before: LLDB `frame variable` — After: `frame variable --children-count 10 user` for one variable's children.
+- This is not presentation etiquette: a flooded context hides the decisive observation and can end the investigation.
+
 ### 4. Gate check
 
 If any answer is "I'm not sure", you are not ready for Phase 1. Investigate until certain. Guessing here cascades into false-positive hypotheses in Phase 2.

package/packages/shared-skills/skills/debugging/references/methodology/02-investigate.md

@@ -39,6 +39,27 @@ If two hypotheses have identical distinguishing evidence, they aren't actually d
 
 ## Phase 3 — Parallel Investigation
 
+### State freshness invariant
+
+**A debug session's state is a snapshot with a lifetime, not a fact you can carry forward indefinitely.**
+- Before any action that mutates the debuggee, re-observe the session's current state.
+- This includes continue, step, side-effecting evaluation, setting or removing breakpoints, and termination.
+- Record the current thread state and stop reason; those are the concrete tells for whether the old plan still applies.
+- An observation from an earlier turn may already be stale when the next action is issued.
+- Turns can be minutes apart while the debuggee runs at full speed, so this failure mode is normal, not exceptional.
+- If the thread state or stop reason has moved, re-observe the new state and do not replay the old plan.
+- Treat every mutation as conditional on the state you just observed, not on a remembered stop.
+
+### Failure-to-recovery taxonomy
+
+| Failure signature | Most likely cause | Next move |
+|---|---|---|
+| Adapter or debugger process failed to start | Wrong binary or missing installation | Verify the tool exists, then re-launch; do not retry blindly. |
+| Breakpoint accepted but never bound or verified | Source path mismatch, optimized-out code, or missing debug symbols | Check the binary was built with symbols and that the debugger-resolved path matches your file. |
+| Attach refused | Permissions, ptrace scope, SIP, or wrong PID | Fix the environment or target identity; a retry will not change it. |
+| No stop event within the expected window | Process is running, the breakpoint is unreachable, or the wait was too short | Pause and inspect threads rather than waiting longer. |
+| Session terminated unexpectedly | The debuggee crashed or exited | Capture the exit and crash evidence before restarting. |
+
 Branch depending on what's available.
 
 ### Path A: Team mode ENABLED
@@ -54,22 +75,22 @@ When the `team_*` tools are present, create a **debug-squad** team and split inv
   "members": [
     {
       "kind": "category",
-      "category": "deep",
+      "category": "deep-low",
       "prompt": "You are the Runtime State Inspector. Your job: attach to the live process, hit breakpoints, read program state (variables, heap, goroutines, stack, registers depending on runtime), and report observed values verbatim. Never guess — if you don't see the value, say so. Report back via team_send_message with file:line / address references and captured values. Never edit source code. Never run git commands. If you need an instrumentation statement added (breakpoint(), debugger;, dbg!, etc.), ask the Lead first."
     },
     {
       "kind": "category",
-      "category": "deep",
+      "category": "deep-low",
       "prompt": "You are the Log Archaeologist. Your job: grep server logs, stderr streams, SDK-internal debug output (DEBUG env, RUST_LOG, GODEBUG, PYTHONASYNCIODEBUG), and correlate timestamps. Produce a timeline of events with latencies. Flag anything that looks like a silent catch, a swallowed rejection, a panic recovered-and-ignored, a success response that contains failure signals (HTTP 200 with empty body, stopReason=error, exit 0 with error-in-stdout). Never edit source code."
     },
     {
       "kind": "category",
-      "category": "deep",
+      "category": "deep-low",
       "prompt": "You are the Reproduction Engineer. Your job: build the smallest reliable repro — a curl command, a vitest/pytest/go test, a tmux script, a Playwright script for browser bugs, a pwntools script for binary targets. It must reproduce on first try and be copy-pasteable by the Lead. Document exact input, expected output, observed output. Save repro artifacts under /tmp/ and tell the Lead to journal them. If the bug is browser-based you MUST use Playwright CLI — do not simulate with curl."
     },
     {
       "kind": "category",
-      "category": "deep",
+      "category": "deep-low",
       "prompt": "You are the Trace Correlator. Your job: take findings from the other members and cross-link them. Build a causal chain from symptom to suspected cause. Identify missing evidence. Propose the next single most-decisive runtime query. Never edit source code; only reason across already-captured evidence. If hypotheses diverge sharply after correlation, tell the Lead immediately — that is the signal for the Oracle Triple."
     }
   ]
@@ -96,7 +117,7 @@ task(subagent_type="explore", load_skills=[], run_in_background=true,
      Runtime state investigation for hypothesis 1: ...")
 task(subagent_type="explore", load_skills=[], run_in_background=true,
      prompt="Log/timing investigation for hypothesis 2: ...")
-task(category="deep", load_skills=[], run_in_background=true,
+task(category="deep-low", load_skills=[], run_in_background=true,
      prompt="Reproduction minimizer for hypothesis 3: ...")
 ```
 

package/packages/shared-skills/skills/debugging/references/methodology/06-fix.md

@@ -1,4 +1,4 @@
-# Phase 6 + 7 — Root Cause Confirmation & TDD Fix
+# Phase 6 + 7 — Root Cause Confirmation & Reproduction-Locked Fix
 
 A cause is not "confirmed" until you can toggle the bug by toggling the cause. Every other level of evidence is correlation, and correlation-driven fixes ship bugs.
 
@@ -51,7 +51,7 @@ The "mechanism" field is the acid test. If you can't write the causal chain from
 
 Red, green, refactor. No shortcuts.
 
-### 1. Red — failing-first test
+### 1. Red — the reproduction as a test
 
 Write a test that fails *specifically because of this bug*. Requirements:
 
@@ -117,6 +117,6 @@ Full suite: <N tests, <M failures — should be 0>
 
 ## The red-green discipline summary
 
-No red test → no proof the fix addresses the reported bug. Only proof it doesn't break tests that already existed.
+No captured failure → no proof the fix addresses the reported bug. Only proof it doesn't break tests that already existed. Keep the reproduction as a test where the repository keeps tests for this behavior; otherwise the captured before/after run is the proof.
 
 A test written *after* the fix might still pass with the fix reverted. If that's the case, the test doesn't lock the bug — it locks something else. Always verify the test fails without the fix and passes with it. The journal should show both outputs.

package/packages/shared-skills/skills/debugging/references/methodology/08-qa.md

@@ -14,7 +14,7 @@ Pick the row that matches the product. Do what it says. Do not substitute.
 |---|---|
 | **CLI tool** | Open `tmux`, run the actual command end-to-end, capture output. Paste the session transcript into the journal. Include exit code, stdout, stderr, side-effect check (files created/modified). |
 | **HTTP API** | Start the real server, hit endpoints with `curl` or `httpie`, inspect response status + body + headers. Hit the specific endpoint that reproduced the bug. If there's auth, use real auth. |
-| **Browser-served web app** | **Drive a real browser via Playwright CLI.** See [tools/playwright-cli.md](../tools/playwright-cli.md). Navigate the exact page/flow that reproduced the bug. Capture screenshot + DOM + network evidence. **Do not substitute with curl** — browsers have state (cookies, localStorage, service workers, client-side JS, viewport-dependent CSS) that curl does not have. |
+| **Browser-served web app** | **Drive a real browser through omowright.** See [tools/browser-qa.md](../tools/browser-qa.md). Navigate the exact page/flow that reproduced the bug. Capture screenshot + DOM + network evidence. **Do not substitute with curl** — browsers have state (cookies, localStorage, service workers, client-side JS, viewport-dependent CSS) that curl does not have. |
 | **Agent / LLM pipeline** | Run the same user prompt that originally failed. Capture the full turn — tool calls, messages, usage counters. **Confirm non-zero usage** (zero usage = still failing silently, see silent-failure check below). |
 | **Background worker / job queue** | Trigger the job through the normal entry point (API call, cron tick, message publish), tail the worker logs, observe completion state in the queue or DB. Don't just call the worker function directly — the trigger path matters. |
 | **MCP server** | Invoke the tool via its actual client (Claude Desktop, Cursor, etc. if available) or `mcp-cli`, not just the HTTP probe endpoint. The MCP handshake itself is sometimes where bugs live. |

package/packages/shared-skills/skills/debugging/references/runtimes/go.md

@@ -42,10 +42,24 @@ dlv exec ./bin/myserver
 # Attach to a running process
 dlv attach $(pgrep myserver)
 
-# Headless mode (IDE / remote attach) — default port 2345
+# Delve's JSON-RPC API (IDE / remote attach) — default port 2345
 dlv debug --headless --listen=:2345 --api-version=2 ./cmd/server
 ```
 
+Delve exposes two distinct machine-readable interfaces:
+
+```bash
+# Debug Adapter Protocol: use this for editors and DAP-aware automation
+dlv dap --listen=127.0.0.1:2345
+
+# Delve's JSON-RPC API: use this for clients built directly against Delve's API
+dlv debug --headless --listen=127.0.0.1:2345 --api-version=2 ./cmd/server
+```
+
+Pick `dlv dap` when the client speaks DAP; pick headless JSON-RPC when you need Delve's
+native API or an existing JSON-RPC client. Both expose structured state, unlike scraping
+an interactive `(dlv)` session.
+
 ### Building a debuggable binary
 
 The compiler inlines and optimizes aggressively in normal builds, which makes stepping confusing. For serious debugging:

package/packages/shared-skills/skills/debugging/references/runtimes/native-binary.md

@@ -107,6 +107,24 @@ print(repr(data[max(0,pos-100):pos+200]))
 
 If you must keep using `strings`, lower the threshold: `strings -n 1 -t x ./target | rg ...`. The signal-to-noise drops sharply but short content is preserved.
 
+### Sanitizer build for a crashing C/C++ binary
+
+If the binary can be rebuilt from C/C++ sources, reproduce the crash with sanitizers before
+trying to infer the fault from stripped machine code. AddressSanitizer catches out-of-bounds
+accesses and use-after-free; UndefinedBehaviorSanitizer reports undefined operations.
+
+```bash
+# Rebuild with source locations and runtime checks enabled
+CFLAGS='-g -O1 -fsanitize=address,undefined' \
+CXXFLAGS='-g -O1 -fsanitize=address,undefined' \
+make clean all
+./target
+```
+
+The sanitizer report identifies the invalid access and its allocation/free or undefined
+operation stack, often making the root cause clear before dynamic analysis. For a binary
+that cannot be rebuilt, continue with the native tracing and debugger workflow below.
+
 Write the triage summary to the journal:
 
 ```markdown
@@ -229,6 +247,26 @@ lldb ./target
 (lldb) image dump symtab ./target
 ```
 
+### Data watchpoints — catch the corruption, not just the crash
+
+When a value is already wrong by the time execution reaches the crash, watch the memory
+address for writes and stop at the instruction that corrupts it. Use the address of the
+field or buffer identified from the static/dynamic hypothesis; see [tools/pwndbg.md](../tools/pwndbg.md)
+for the richer pwndbg watchpoint workflow rather than duplicating it here.
+
+```text
+# lldb: watch writes to an address (replace with a valid expression/address)
+(lldb) watchpoint set expression -- <addr>
+
+# gdb: stop on writes, or on reads when a read is the first observable symptom
+(gdb) watch *(<type> *)<addr>
+(gdb) rwatch *(<type> *)<addr>
+```
+
+A watchpoint is most useful after narrowing the suspect object: continue from its
+allocation or initialization, and inspect the backtrace and writer when it triggers.
+Hardware watchpoint slots are limited, so remove broad watchpoints before adding more.
+
 **Function interception via `DYLD_INSERT_LIBRARIES`** (macOS equivalent of `LD_PRELOAD`):
 
 ```bash