ns-optimize-function

name	ns-optimize-function
description	Optimizes a specific local Node.js function selected by the user. Use when the user points to code and asks to make it faster, improve throughput, reduce CPU/memory cost, or fix a slow function. Requires workspace source; analyzes blast radius, proposes a behavior-preserving rewrite, and hands off to benchmark validation. Not for live N|Solid diagnostics alone.

1. Acquire the Target Function

• The user selects a function via code-lens, names it, or pastes its code. Read it from the workspace.
• If they name it but don't point at a location, search the workspace for the definition and confirm the match before proceeding. Do not guess which definition they meant when multiple exist — ask.
• Record the exact file path, start/end lines, and the function signature.

2. Analyze Context & Impact

This is the grounding step. Do not write any optimization yet.

• Read the function body and everything it references (helpers, constants, external imports, closures).
• Search the workspace for call sites and tests to understand real usage and the actual input shapes callers pass in.
• Assess and state explicitly:
  • What it does and its current complexity — the algorithmic shape (loops, nested iterations, recursion, allocations, serialization, I/O).
  • Blast radius — how many call sites, whether it sits on a hot path (request handler, render, hot loop) or a cold path (startup, config load), sync vs async, and any concurrency/fan-out.
  • Optimization worthiness — is it actually worth optimizing? A cold startup path is rarely worth it; a per-request function is. If it is NOT worth optimizing, say so plainly and stop here rather than optimizing for the sake of it.

3. Baseline Benchmark

Measure before changing anything — optimization without a baseline is guessing.

• Delegate to the ns-benchmark-run skill to benchmark the current implementation. It builds the benchmark inputs and runs the measurement.
• Use the real inputs derived from step 2 (call sites / tests), not invented arguments.
• Record the baseline ops/sec. This is the number the optimization must beat.

4. Propose the Optimization

• Based on step 2's analysis, design ONE optimized rewrite targeting the dominant cost (algorithmic, allocation, I/O, caching, etc.).
• Present the change as a before/after diff with a short rationale tied to the specific cost you identified.
• Human in the loop: ask the user to approve the rewrite before benchmarking it. Do not run the optimized benchmark until they approve.

5. Validate (delegate to ns-validate-optimization)

• After approval, use the ns-validate-optimization skill to verify the improvement. It builds the benchmark inputs, runs the A/B comparison between the original and optimized code, and retries up to 3 times until the improvement clears the effectiveness threshold.
• Handoff payload: original code, optimized code, file path/lines, entry points, call-site/test evidence, and contract notes.
• Do NOT embed the benchmark mechanics here (run_benchmark, get_benchmark_result, compare_benchmarks, the retry loop) — ns-validate-optimization owns all of that.

6. Final Wrap-Up (Do Not Duplicate Validation Report)

• ns-validate-optimization owns the full benchmark report, save-to-disk prompt, and benchmark evidence/logs.
• After validation returns, give a concise wrap-up only: function/location, impact/worthiness, optimization rationale, final verdict, and saved validation report path if one exists.
• If validation exhausted 3 attempts without clearing the threshold, say so plainly and name the best measured attempt; never claim success.
• Do not write or save a second optimization report unless the user explicitly asks for a combined narrative report.
• If the workflow stops before validation (not worth optimizing, ambiguous target, or no approval), provide a short inline decision summary instead of a report.

Guardrails

• Never optimize a function you have not benchmarked a baseline for first.
• Never skip the impact/worthiness assessment (step 2). A cold path is not a valid optimization target — say so and stop.
• Never embed benchmark mechanics. Delegate measurement and validation to ns-benchmark-run and ns-validate-optimization.
• Never propose an optimized rewrite that changes the function's contract (arguments, return shape, side effects, error behavior) unless the user explicitly approved that contract change. ns-validate-optimization compares the same contract — a different one invalidates the A/B comparison.
• If no tests or call sites exist, say so and derive the narrowest defensible inputs from the code itself — do not invent workloads.
• Never report a successful optimization that did not clear the effectiveness threshold. Report the best attempt and that it fell short.