@bompus/house-rules 0.11.0 → 0.14.0

package/skills/hr-benchmarking/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hr-benchmarking
-description: Benchmark equivalent work with repeated timing, CPU and memory measurements under stated inputs and controls, and check whether saved results support a performance claim. Use when asked to benchmark, to measure which option is faster or uses less memory, or to time agent or model runs. Public model leaderboard research is outside this measurement workflow.
+description: Benchmark equivalent work with repeated timing, CPU and memory measurements under stated inputs and controls, and check whether saved results support a performance claim. Use when asked to benchmark, to measure which option is faster or uses less memory, or to time agent or model runs. Not for public model leaderboard research.
 ---
 
 # Benchmarking
@@ -21,11 +21,17 @@ configurations or capacity modes. Keep untested, invalid and unsupported
 candidates visible with reasons. A subset comparison establishes results only
 for its tested scope, not a winner across the full inventory.
 
+Test the newest stable release of each candidate. When the version installed
+or deployed differs, say so in the results, and ask which to test if the
+request does not settle it. When told to use an older version, use it and
+offer the newest as an alternative.
+
 Before running, list the selected engines, workloads, metrics, controls and
 repetitions. Count the planned runs explicitly, including controls and stages;
 state which decision each retained dimension helps make. Choose combinations
 for that decision rather than automatically running every combination. Use a
-broader matrix when its required coverage is stated.
+broader matrix when its required coverage is stated. State the benchmark's
+expected wall-clock time, waits included, before the first run.
 Name the measurement unit: request, operation, batch or whole command. State
 whether setup, startup, compilation, input loading, retries and cleanup count.
 
@@ -54,12 +60,37 @@ Identify the limiting resource from CPU versus wall time, resource counters or
 a separate profile. Check that throughput is possible given the machine and
 input. When the generator limits the result, report that limit.
 
+Before changing a component to remove a suspected cost, attribute time to that
+component in the real workload with a profile or a counter. For fast feedback,
+benchmark each changed piece through its actual production entry point with
+representative fixed inputs and equivalent consumed outputs. Do not benchmark a
+copied implementation or stub out work material to the comparison.
+
+Compare each piece before and after against its immediate predecessor. Before
+running, declare integration milestones when changed pieces enter the consuming
+workload. Keep that workload before any piece changes as the original baseline.
+At those milestones, compare the integrated workload with both its immediate
+predecessor and the original baseline to track cumulative effects. Plan applicable
+caller and integration checks for copying, serialization, startup and orchestration
+costs that isolation excludes. Run those checks at the milestones and report
+results or specific coverage limits. Re-time the change in the workload that uses
+it at those milestones; a full-application run is not required after every piece.
+An isolated gain does not establish an end-to-end gain. A setting that ran 7.6
+times faster in isolation changed a 33 s indexing run by 0.1 s.
+
+Select metrics for the question and limiting resource: wall time or latency,
+memory, disk I/O, CPU, throughput, errors and output size as relevant. State each
+metric's unit, process scope and interval; distinguish peak process memory from
+retained memory, logical bytes from physical storage I/O, and warm from cold cache
+state. Cache hits and delayed writeback can hide storage costs; record unavailable
+counters and attribution limits rather than inferring physical I/O from logical
+bytes. Do not require irrelevant additional counters; retain the CPU and memory
+observations required below.
+
 ## Measure without changing the experiment
 
-Coordinate resource use under the host's rules. During isolated local performance
-measurements, the measuring session only monitors. Other sessions may do light
-work within the run's resource limits. Keep measured files, toolchains and
-services unchanged.
+Keep measured files, toolchains and services unchanged, and keep other work on
+the machine from competing with the run.
 
 Prefer removing competing work to raising priority. Record effective CPU and
 I/O scheduling policies and memory protections; keep them equal across arms.
@@ -69,139 +100,37 @@ rather than assuming their omission resets either. Use restricted affinity or
 changed priority only for representative deployment settings, an explicit resource
 agreement or a stated sensitivity question. Record the reason and effective values.
 Preserve frozen protocols and report constrained results within their tested scope.
-
-Treat a priority or affinity change as a separate sensitivity pilot under the host's rules, with preset variation
-criteria and retained raw results. Verify that the controls apply and that
-dependencies and monitoring still progress before adopting them for the
-declared experiment. Priority changes never replace admission checks, resource
-caps or pressure rejection. Read [scheduling controls](references/tools.md#scheduling-controls)
-before choosing them. When brief bursts from other sessions keep failing host-wide
-admission on a shared host, read the [fenced-core arm](references/tools.md#fenced-core-arm)
-before proposing one; it needs the user's authorization. For questions about negative, zero or positive nice values,
-read the [recorded priority findings](references/priority-findings-20261006.md)
-before proposing another experiment.
-
-Classify the timed region against the host's budget for concurrent light work.
-A local phase is heavy when measured or expected CPU, memory or I/O exceeds
-that budget. Inspect the command, its hooks, wrappers and children before calling
-demand
-unknown. Inspection can qualify bounded ordinary work within that budget;
-missing resource samples alone does not require a trial. When inspection leaves
-potentially incompatible demand unresolved, contact the active reservation owner
-or host coordinator. If neither is identified, ask the operator. Launch that
-workload only after recording agreement on a bounded trial with CPU, memory and
-I/O limits, or an exclusive run window. Resolve input and authorization conflicts
-separately; resource admission does not override them.
+Read [scheduling controls](references/tools.md#scheduling-controls) before
+choosing them.
 
 Apply worker limits to requested processing concurrency. Report sampled OS-thread
 counts separately; runtime background threads are not processing workers. A
-thread count alone does not establish CPU contention. Use CPU, memory, I/O and
-elapsed-time controls for the admitted resource budget. Keep thread count
-diagnostic unless a host limit or experiment requirement separately justifies
-using it to stop or reject a run.
-
-When an existing admission binds thread count, obtain revised admission before
-relaxing that condition. Preserve the other controls, held inputs and original
-run verdicts. Record the revised observer and limits before execution.
-
-For an unknown competing job, record a preset time or query limit, then inspect
-its process identity, actual demand and access to measured inputs. Stop at that
-limit. A cap, service name or active state alone does not establish incompatible
-work. Keep unresolved overlap or observer gaps unqualified; input mutation remains
-incompatible even at low demand.
-
-A retained benchmark lock does not pause other sessions or reserve every phase
-of their tasks. Qualified non-heavy checks, edits and coordination proceed without
-acquiring that lock while staying within the concurrent-work budget and preserving
-measured inputs. Classify actual commands and children, including hooks; reuse
-qualification only for comparable inputs, runtimes and worker counts. When
-inspection leaves demand unresolved, identify the missing evidence and arrange
-the bounded qualification above. Defer only the incompatible phase, naming its
-resource or input conflict;
-do not use lock ownership alone to block qualified non-heavy work. Keep repository
-integration and installation write locks separate from benchmark admission.
-
-Reserve the host only for heavy local phases or deliberately isolated local
-performance measurements. Remote model
-inference, light CLI/API work and remote waits need no exclusive slot; a
-memory cap or elapsed-time record alone does not establish heavy work. For
-remote agent/model evaluations, record the timing regime and concurrent local
-work. Apply the local admission and pressure rules below when measuring local
-performance, rather than treating every model call as a CPU benchmark.
-
-Before collecting results, declare required observers, their measurement interval
-and coverage criteria. Require successful execution and recorded coverage that
-meets those criteria. Preserve observer exit status, errors and missing samples;
-reject evidence with unexplained observer failures or insufficient coverage.
-Require empty stderr only when the observer's declared contract requires it;
-documented harmless diagnostics alone do not invalidate observation.
-
-Declare observer CPU, resident-memory and I/O budgets separately from foreign-load
-and pressure gates. Include every collector and reader, with process birth
-identities and aligned intervals. Record CPU time, average core-equivalent use,
-workload-relative CPU, resident peaks, logical log bytes and attributable storage
-I/O. Separate setup from collection; disclose missing platform counters and
-shared provider or writeback costs. A log-byte count is not physical disk I/O.
-Retain over-budget runs with an over-budget status and exclude them from accepted
-performance evidence. Declare any stop rule and replacement limit before
-execution. When automation applies a stop rule, compute it with the same code as
-the acceptance analysis. Record budget failures separately from foreign-load and pressure
-failures.
-
-Choose budgets for the host, workload duration and decision precision; there is
-no universal workload-relative CPU percentage. A budget permits collection but
-does not prove unchanged latency. Before claiming negligible observer impact or
-a small decisive gain, test sensitivity to observation separately with balanced
-controls and a preset precision criterion. Retain inconclusive controls; do not
-subtract observer CPU from workload wall time. Assign and record each run's
-protocol version before execution. A changed observer budget creates a new
-protocol version. Keep historical rejection verdicts with their original version.
-
-Before each arm, inspect CPU outside the measuring scope, memory headroom and
-pressure, swap and competing CPU, memory or I/O jobs. Use the host's admission
-limits; when it has none, declare the metrics and pass/fail thresholds before
-collecting performance results. Start only when every admission condition passes.
-During measurements, attribute CPU, load and resident memory to the recorded
-benchmark process tree or resource scope before calling them competing work.
-Expected benchmark utilization is not contention; total host CPU and load
-average include it. Collect boundary counters adjacent to the measured work,
-with unrelated probes outside that interval. Record sample times and observer
-overhead. A counter interval extending past completion cannot by itself
-establish overlap. Keep post-run observations diagnostic and use a fresh
-settled interval before the next arm.
-
-Keep uncalibrated activity counters diagnostic. Before using an activity cutoff
-to reject measurements, establish its relevance through separate sensitivity
-evidence with comparison conditions and an interference criterion set before
-analysis. Retain raw observations and inconclusive outcomes. Preserve declared
-pressure and observer checks; distinguish a conservative limit from evidence
-that interference occurred.
-
-Reject a run when inputs change, competing work crosses a declared contention
-limit, or a declared pressure condition fails. Before collecting performance
-results, define pressure rejection using stall duration, swap activity and
-memory-limit/OOM events; name any additional signals and their thresholds.
-Set a stall-duration budget from the experiment's timing precision. Record
-smaller stalls without rejecting them. Stalls exceeding the budget, swapping
-or memory-limit/OOM events invalidate measurements even when the benchmark
-causes them. Resource rejection invalidates the measurement; it alone does not
-establish an implementation defect. Investigate uncertain overlap and repeat
-affected runs within authorized retry budgets before a decisive comparison.
-A light session's presence alone is not rejection evidence.
-
-Declare per-case retry budgets before attempts; a budget grants no retry
-authority. Retain rejected attempts outside accepted samples. A later qualifying
-attempt neither erases a rejection nor relaxes its gates. After rejecting a case,
-continue other independently selected cases only when their admission passes
-and the failure cannot invalidate shared controls. Otherwise hold affected cases.
-
-Hold reservations during heavy local phases or declared isolated local performance
-measurements. Release them during remote waits, light work and reviews.
-Declare finite phase boundaries or stopping conditions, release at those
-boundaries and seek fresh admission for the next phase. While waiting, keep the
-blocked phase in the ledger and advance already-authorized independent light
-work within the active measurement's allowance. Preserve measured inputs;
-backlog presence does not authorize new implementation.
+thread count alone does not establish CPU contention; keep it diagnostic unless
+the experiment separately justifies using it to reject a run.
+
+Before collecting results, set the criteria for rejecting a run: competing
+load, swapping and memory-limit or OOM events, each with its metric and
+threshold. Check the machine against them before each arm and watch them
+throughout the measured interval. A run that fails them, or whose inputs change, is rejected even when the benchmark caused the
+failure. A rejection invalidates that measurement; it does not by itself show
+an implementation defect. Keep rejected runs outside the accepted sample and
+report them; a later passing run neither erases a rejection nor loosens the
+criteria.
+
+Attribute CPU, load and resident memory to the recorded benchmark process tree
+or resource scope before calling them competing work. Expected benchmark
+utilization is not contention, and total host CPU and load average include it.
+Keep an activity counter diagnostic until separate evidence shows its cutoff
+matters. Collect boundary counters adjacent to the measured work, with
+unrelated probes outside that interval, and record sample times. A counter
+interval extending past completion cannot by itself establish overlap; keep
+post-run observations diagnostic and let the machine settle before the next arm.
+
+Before claiming negligible observer impact or a small decisive gain, test
+sensitivity to observation separately with balanced controls and a preset
+precision criterion. Retain inconclusive controls; do not subtract observer CPU
+from workload wall time. For remote agent or model evaluations, record the
+timing regime and concurrent local work.
 
 Screen correctness and quality first, then use one run per selected arm to
 explore timing and resource behavior. Preserve screened-out results and their
@@ -212,23 +141,37 @@ Before exploratory runs, define the decision-relevant signal for selecting
 comparisons for confirmation. Choose comparisons that meet that signal, plus
 decision-critical comparisons, for repeated confirmation; keep necessary controls.
 Set the confirmation plan before its runs and update the explicit run count
-when the scope changes. Repetition counts depend on the
-decision and observed variation; there is no universal minimum.
-
-For a performance claim, add alternating runs to assess run-to-run variation.
-Before the first run used in that claim, set a repetition count or stopping
-rule and a reproducible variation criterion (statistic and threshold).
+when the scope changes.
+
+The default stopping rule for a performance claim is 3 runs per arm. Add 2 more
+per arm only when the arms' ranges overlap or the effect is near the noise,
+meaning the gap is within the variation criterion set below. 5 per arm is the
+cap. If 5 runs per arm leave the comparison unresolved, report it as
+inconclusive rather than adding runs. Use another count only when the user asks
+for it or a run is too long to repeat 3 times, and declare it before the first
+run, with the reason. Alternate the arms in every run so drift reaches each arm.
+
+For a performance claim, assess run-to-run variation from those alternating runs.
+Treat variation as already known only when earlier repeated runs of the
+same variant, build and input used the same workload, host, run conditions and
+variation statistic, and met the repetition count or stopping rule declared for
+this claim. Otherwise include an A/A arm,
+which runs the same variant twice in the same alternation. Its spread is that
+comparison's own noise floor, and it can supply the preset variation statistic.
+Before the first run used in that claim, set a reproducible variation criterion
+(statistic and threshold), and the stopping rule if it differs from the default.
 
 For short or tail metrics, such as the longest stall in a run, give the
 threshold an absolute floor or use a percentile or count metric; a percentage
 of a single small maximum can fail on the workload's own variation.
 Retain every result. Keep pilots that informed the plan separate from the
 claim's sample. Capture raw results, exit status, elapsed time, CPU and memory
-observations. Report admission and monitoring overhead separately from the
+observations. Report monitoring overhead separately from the
 measured workload; batch compatible probes when they dominate elapsed time.
 Report the selected repetition count or stopping rule, variation statistic and
-threshold, sample count, median and range. Apply the preset
-criterion and treat a gap within run-to-run variation as inconclusive. Profile
+threshold, sample count, median and range. Always give the run count and the
+range with any central value, never a bare average. Apply the preset
+criterion and report a gap within run-to-run variation as no clear change. Profile
 separately from the runs used to claim a speed difference.
 
 When using saved evidence for a performance claim, bind archived inputs, source,
@@ -268,8 +211,8 @@ Batch latency percentiles describe batches, not individual requests.
 
 Keep the full workload, versions, conditions, repetitions, output identity,
 errors and measurement units in the measurement record. Include excluded costs,
-coverage limits, collector overhead, scheduling, resource caps, admission checks
-and rejected attempts there.
+coverage limits, collector overhead, scheduling, resource caps, pre-run
+machine checks and rejected attempts there.
 
 Pull requests and other change summaries show the workload, baseline and
 candidate, measured results, relevant checks and limits that affect the claim.
@@ -282,19 +225,39 @@ percent change or a times improvement. Use the metric's direction and label
 worsening, unchanged or inconclusive results. With a zero or missing baseline,
 show an absolute change or state that the benefit cannot be calculated.
 
-Use 3% as the default practical no-clear-change band for reported differences.
-This is a reporting convention, not a statistical margin of error. Use the
-variation statistic and threshold declared before collecting results. When that
-threshold, expressed as a percentage of the baseline, exceeds 3%, widen the
-reporting band to at least that percentage and name the statistic and threshold.
-If the variation criterion cannot support a percentage band, keep its result
-separate and label unsupported differences inconclusive. A change outside the
-band still needs qualified evidence and must meet the declared variation criterion. Set a different
-precision target before collecting results when the workload requires it;
-changing presentation does not change frozen acceptance or rejection gates.
+There is no minimum gain size. A favorable difference counts as a gain when it
+lies outside the variation criterion declared before the first run (the comparison's
+own run-to-run spread, from its A/A arm or already-known variation, as a
+percentage of the baseline) and the outputs are identical. Report a gap inside
+that criterion as no clear change, and name the statistic and threshold beside
+it. An unfavorable difference outside it is a regression; label it worsening.
+Report memory and CPU costs beside the gain. If the variation criterion cannot support a percentage, keep its result
+separate and label unsupported differences inconclusive. Changing presentation
+does not change frozen acceptance or rejection gates.
+
+Show a comparison of three or more variants or conditions as a chart beside the
+before/after table, unless every row is no clear change. Choose the chart for the
+question:
+
+| Question                         | Chart                                      |
+| -------------------------------- | ------------------------------------------ |
+| Repeated runs of each variant    | Dot plot of every run, mean marked         |
+| Conditions crossed with variants | Grouped bars, baseline as a reference line |
+| Ranking of options               | Sorted horizontal bars                     |
+| Resource cost (CPU, memory)      | Bars per variant, one panel per resource   |
+| Change with load or time         | Line chart                                 |
+
+Put units and run counts on the axes, start bars at zero, mark a gap inside the
+variation criterion as no clear change, and give the chart an explicit background colour so
+it reads the same on a light or a dark page.
+In a pull request, the headline chart and when it may be skipped come from
+`hr-writing-pr`; this table applies to any other chart.
 
 For agent, model, rule or skill comparisons, distinguish development cases
-from held-out cases and report runs per case. Include a one-line instruction
+from held-out cases and report runs per case. Check each case for a ceiling: a
+case every arm already passes cannot show a pass-rate improvement. Report it
+apart from the cases that could, and report any metric the case does not
+saturate (time, cost, graded quality) on its own. Include a one-line instruction
 control when claiming an improvement from a rule or skill. Keep helper,
 setup and retry costs visible. Before collecting results, define a per-case
 contribution threshold. If a case exceeds it, report results both with and
@@ -312,5 +275,5 @@ and rework time. Keep returned usage units separate from attributable account
 charges; unknown attribution remains unknown.
 
 Record every experiment, rejected ones included, with the observed result and
-disposition. End with adopt, reject or inconclusive, and the evidence for that
+what was decided. End with adopt, reject or inconclusive, and the evidence for that
 decision. Any implementation or publication still follows the user's scope.

package/skills/hr-benchmarking/references/javascript.md

@@ -15,3 +15,116 @@ startup or transformation separately when it is part of the question.
 [Node type stripping](https://nodejs.org/api/typescript.html) performs no type
 checking and ignores `tsconfig.json`. A successful direct `.ts` execution does
 not establish TypeScript correctness.
+
+## Running under Bun versus Node
+
+Confirm the runtime before comparing: print `process.execPath` or
+`process.versions.bun` from inside the code under test, in worker threads too.
+Verified on Bun 1.4.x:
+
+- `bun x vitest` is not Bun. `bun x` honors the tool's `#!/usr/bin/env node`
+  shebang and runs the whole suite under Node. Use `bun --bun x vitest run`.
+- `node` can resolve to Bun. On Bun 1.4.3, a package script that calls `node` printed Bun's
+  version under `bun --bun run` and Node's under plain `bun run`; a `Bun.spawnSync(['node', …])`
+  reached real Node in both modes. The shim depends on Bun's `run.bun` setting, which defaults
+  on only when `node` is absent from `PATH`. Check `process.versions.bun` in the spawned process,
+  and filter `PATH` entries matching `/bun/i` when you need real Node.
+- With no `node_modules` up the tree, `require.resolve` falls back to Bun's global
+  install cache ([oven-sh/bun#42893](https://github.com/oven-sh/bun/issues/42893)).
+  Pass `--no-install` for a hermetic "not installed" result.
+- File-path and `{ eval: true }` workers both run under Bun, and `node:sqlite` and
+  NAPI `.node` addons load.
+- Many busy, allocating workers wait on each other's parallel GC marking
+  ([oven-sh/bun#44186](https://github.com/oven-sh/bun/issues/44186)); with 8
+  workers `BUN_JSC_numberOfGCMarkers=1` roughly halved wall time. Attribute with a
+  profiler before concluding anything about worker scaling.
+- Node 26.11 renamed its synchronous SQLite classes to `Database` and `Statement`
+  (`DatabaseSync` and `StatementSync` stay as aliases) and caches common property
+  keys in its SQLite bindings. Record the exact Node version beside SQLite
+  results; an older baseline does not establish the gap on the new runtime.
+
+## Choosing what to hunt
+
+Start with something a user waits for. Use a representative workload and data size, then count the work before timing individual functions.
+
+- Count messages and bytes per action, SQL statements, subprocesses, React commits, queue depth and oldest-item age. Measure idle CPU, event-loop delay and utilization. Use a CPU profile to attribute expensive work; delay alone does not identify its cause.
+- Check repeated work first: whole-state rebuilds after small updates, serialization per subscriber, repeated parsing or validation, N+1 queries and per-row transactions. Check for backpressure when producers outrun consumers.
+- Vary one input size while holding the rest fixed. Look for quadratic growth, large linear costs, and fixed costs paid too often. A high count alone does not establish a bottleneck.
+- Check work that survives its owner: listeners, timers, caches, pending requests and reconnect loops. Measure repeated open/close cycles and hidden, idle and disconnected states separately.
+- Profile startup imports, rendering and layout, compression, logging and tracing when they appear in the user-visible path. Investigate engine-specific tuning only when a profile identifies the relevant hot loop.
+
+Record null results and their tested conditions. Stop a candidate when its measured benefit is within the declared variation criterion, or when it cannot materially improve the chosen user-visible outcome. Do not use a universal percentage cutoff.
+
+### Deciding whether to move synchronous work
+
+Prioritize hot paths, then inspect less frequent paths for long individual stalls. A rare operation can still delay unrelated requests.
+
+Measure the longest blocked interval and the average blocked milliseconds per call multiplied by calls per second. The product is milliseconds blocked per second; divide by 1,000 to estimate the duty-cycle fraction. This average does not describe burst latency. Compare against the application's actual response and frame budgets. A 60 Hz frame is about 16.7 ms; higher refresh rates leave less time.
+
+Reduce unnecessary work first. Consider reuse, bounded caching, batching and yielding between chunks when their correctness requirements fit. A promise or `async` wrapper does not make CPU work leave the event loop.
+
+Use the runtime's asynchronous APIs for supported I/O. They add scheduling and completion overhead and can contend for a shared thread pool. For CPU work, compare chunked yielding with a reused [worker or worker pool](https://nodejs.org/api/worker_threads.html). Include worker startup, message and clone or transfer costs, queueing, memory, cancellation and shutdown. Do not create a new worker for every small call by default.
+
+Compare equal completed work under representative concurrency. Report wall time, CPU, memory and unrelated-request latency beside the longest stall. Offloading may improve responsiveness while costing more total CPU; state that tradeoff. A saturated worker queue can erase the improvement. There is no universal payload size or duration at which async or a worker wins.
+
+### Runtime checks
+
+- **Cloudflare Workers:** [deployed timers](https://developers.cloudflare.com/workers/runtime-apis/performance/) such as `Date.now()` and `performance.now()` advance after I/O, so they cannot time an uninterrupted CPU section. Local Wrangler uses workerd and permits advancing timers; use it for attribution and confirm deployed behavior with platform CPU metrics. Check current platform limits. A Durable Object runs JavaScript on one thread, but requests can interleave across awaits; distinguish synchronous blocking from storage gates and explicit concurrency controls.
+- **Bun:** JavaScriptCore and V8 can have different hot paths. Verify the runtime and use its profiler; remeasure relevant changes on each supported runtime.
+- **Electron:** attribute renderer and main-process work separately. Synchronous IPC blocks the caller; expensive main-thread work can delay all windows.
+- **React Native and web:** use production builds. Count commits per actual streamed update or action, not per estimated token. Separate JavaScript work from layout, paint and native UI work. Record visibility and observer overhead.
+
+## Event-loop and server-code measurement
+
+Each event-loop thread of a Node or Bun server runs request handling, timers and
+synchronous database calls. A slow call matters when it holds that thread, so
+measure the hold, not only the duration. (M) marks a result measured on one
+workload and host, not a benchmark.
+
+- **Measure the longest stall, not wall time.** Run a 1 ms `setInterval` that
+  records the largest gap between ticks while the call runs, after letting the
+  loop settle first. Report it beside wall time. They differ: a snapshot read took
+  79 ms of wall time and held the loop for 12.6 ms because the runtime yielded
+  between steps (M). `perf_hooks.monitorEventLoopDelay` has a resolution of at
+  least 1 ms, so use it for coarse trends, not for claims of a few ms. State the
+  probe interval beside any figure near it.
+- **Time the real function, not a copy.** A copied string-appending coalescer
+  looked quadratic; the real one showed equal CPU and equal longest stall within
+  noise, because V8 joins repeated concatenation lazily (M). A replica that leaves
+  out framework overhead is only a lower bound. Run server code inside the
+  project's own test runner with its in-memory test layer, write results to a file
+  because runners often swallow `console.log`, and delete the temporary test
+  afterwards.
+- **Count volume when volume is the cost.** For code that emits events or
+  messages, feed a fixed synthetic input through the real component and count the
+  events and serialized bytes at several sizes. Counts are deterministic, so they
+  need no repetitions; stall and wall time still do. One adapter emitted three
+  events per streamed chunk, two of them carrying the whole reply so far: 15,003
+  events (three per chunk plus one closing update of each) and 263.6 MB for 5,000
+  chunks of 10 characters (about 125 MB for each of
+  the two full-text copies), growing about 3.3 to 3.6 times per doubling, with a
+  longest stall under 6 ms (M). That is a volume problem, not
+  a stall.
+- **Separate loop time from child-process time.** Work done by an asynchronously
+  spawned process uses CPU but does not hold the loop. Count such a spawn as loop
+  cost only for its spawning and parsing. `spawnSync`, `execSync` and `execFileSync` block the
+  loop for the child's whole lifetime, so count that time as a stall.
+- **Prove that work left the loop with a test that cannot pass otherwise.** Hold
+  the main connection or thread busy (blocked on a latch) and
+  assert the moved work still completes. A speed measurement alone cannot show
+  where the work ran. Moving one read off the loop took the longest stall from a
+  median 165 ms to 2.5 ms over 12 runs per arm, with no clear change in wall time, measured with a 2 ms probe (M).
+- **Measure retention with forced garbage collection.** Run N synthetic sessions
+  or turns, force a collection, and compare heap deltas with the suspect field
+  kept and dropped, keeping the owner reachable to the end. One researcher's run, not
+  repeated, kept only the two fields that were read and went from 61.45 MiB to
+  2.10 MiB over 30 sessions of 10 turns of 200 KiB.
+- **Time startup on the built artifact, interleaved.** Alternate arms on
+  one build, using the default run count in [the skill](../SKILL.md). An
+  environment variable can stand in for an API
+  call, but note what it changes (it also reaches child processes). A V8 compile
+  cache took a CLI's `--help` from a 554 ms median to 381 ms over 11 runs (M).
+- **Treat another researcher's numbers as leads.** Of three top candidates from a
+  model's blind read-only pass, re-measuring left one refuted, one mostly covered
+  by existing work and one real but small. Re-run a lead with the real function
+  and the stall probe before acting on it.