[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7AQZHN5CTTRAPRHSYWA4WKF":3,"skill-same:01M7AQZHN5CTTRAPRHSYWA4WKF":84},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7AQZHN5CTTRAPRHSYWA4WKF","provenfast",null,"Measurement-first performance improvement for any app, repo, OS, or agent harness. Default is a lean pass: briefly triage the main interactions, fix the largest worthwhile bottlenecks with proportionate effort, verify affected behavior and before\u002Fafter performance, and finish when the target (the user's, or a provisional one stated up front) is met. Reuse existing tools; add a new regression gate only when a regression has recurred or on request. Extended sprints and ongoing monitoring require an explicit request. Use for \"make it faster\", \"speed up\", \"latency\", \"slow\", \"startup time\", \"jank\", \"frame drops\", \"perf regression\", \"benchmark\", \"profile\", \"ratchet\", \"wall clock\", \"instruction count\", \"call count\", or a perf CI gate. Not for one-off micro-tuning without a user-visible journey.","ham-zax\u002Fwebharness","ham-zax","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F81289670?v=4","01M7AQGHAV4TPYCAZY23S7SVSC","Ahmed Hamza","01M7AQGHBCFJYE7KWZ34W9HEGH",0,"MIT","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: provenfast\ndescription: \"Measurement-first performance improvement for any app, repo, OS, or agent harness. Default is a lean pass: briefly triage the main interactions, fix the largest worthwhile bottlenecks with proportionate effort, verify affected behavior and before\u002Fafter performance, and finish when the target (the user's, or a provisional one stated up front) is met. Reuse existing tools; add a new regression gate only when a regression has recurred or on request. Extended sprints and ongoing monitoring require an explicit request. Use for \\\"make it faster\\\", \\\"speed up\\\", \\\"latency\\\", \\\"slow\\\", \\\"startup time\\\", \\\"jank\\\", \\\"frame drops\\\", \\\"perf regression\\\", \\\"benchmark\\\", \\\"profile\\\", \\\"ratchet\\\", \\\"wall clock\\\", \\\"instruction count\\\", \\\"call count\\\", or a perf CI gate. Not for one-off micro-tuning without a user-visible journey.\"\n---\n\n# ProvenFast\n\n> If it can be measured, it can be improved. Once a metric exists, an agent can\n> iterate against it without waiting for field data.\n\nDistilled from Anthropic's August 2026 claude.ai speed sprint\n(\u003Chttps:\u002F\u002Fclaude.dev\u002Fblog\u002Fhow-we-made-claude-ai-faster\u002F>). In that sprint, an\nagent working in one shared channel made the core journeys 3.1x faster\n(geometric mean across 13 metrics) in two weeks. Anthropic reports 3,000+\nmerged changes without a single customer-facing incident or rollback. That is\ntheir claim, and a critic later found UX bugs it does not capture\n(`references\u002Ffield-lessons.md` B1). The useful part is not any single trick but\nthe **loop**, the **metric ladder**, and the **guardrails** below. They work for\nany stack.\n\n## Default: the most improvement for the least effort\n\nDeliver the largest practical improvement to ordinary users for a proportionate\ntotal cost (section 7). Unless the user explicitly\nasks for deeper work, run the **lean pass**:\n\nKeep a normal invocation bounded to the current task. Complete worthwhile fixes\nand verification, then return the result; ongoing optimization is separate work.\n\n1. **Triage briefly, then focus.** If the user names a slow interaction, start there. For a broad request, briefly inspect startup, navigation, and the main interaction using available timings or traces, then select the largest worthwhile bottleneck. Measure on a representative device and input, including a realistic large input when size affects the cost. Use the user's target; if there is none, state a provisional target grounded in the baseline and the observed pain, and proceed.\n2. **Measure lightly.** Before\u002Fafter wall clock (median of at least 3 runs) and a targeted trace or profile are usually enough. Add measurement only when it resolves uncertainty or makes the next experiment cheaper.\n3. **Fix the dominant cost with proportionate effort.** Prefer existing tools and simple changes: fewer duplicate fetches, narrower re-renders, smaller payloads, startup work deferred, better data loading (catalogue in section 4). A larger bounded change, such as moving parsing to a worker, can be the efficient choice if it removes the main bottleneck. Weigh user benefit against total cost (section 7); line count alone does not decide.\n4. **Verify what the change could break.** Run the affected tests. When the change touches caching, fetching, or saving, check freshness and persistence (section 5). Scale verification to risk.\n5. **Stop at the target** (section 7). The target is the user's, or the provisional one from step 1; meet it, then finish. Past the target, continue only while another improvement is both clear (the profile shows it) and inexpensive (a small change with existing tools). Avoid repeated searches for tiny gains. Report the measured result and any significant remaining bottleneck; label unmeasured gains as estimates or unknown.\n\n**Deep mode** needs an explicit request for an extended performance project: exhaustive investigation, specialized benchmark infrastructure, runtime replacement, or ongoing deploy monitoring. A broad app request permits brief triage of several journeys. A lean pass may reuse an existing counter, gate, or rollout mechanism. It adds a new regression gate only when the same regression has already recurred or the user asks for one. A request for one gate authorizes that gate, not a sprint. Material scope expansion still needs agreement.\n\nThe rest of this file is a toolbox for both modes. Read only relevant references,\nand use only the measurements and safeguards justified by the selected change.\nSteps marked *deep mode* apply only to the requested deeper work.\n\n## 0. Adapt before you measure\n\nDo this once per task, only as far as the journey needs. It decides which tools and which section of the references apply.\n\n1. **Harness.** Map the verbs in this skill to your tools (table below). If you cannot run commands, produce the exact commands and ask the user to run them and paste the output.\n2. **System.** If the environment or available tools are unclear, run `scripts\u002Fdoctor.sh [repo]` (Linux\u002FmacOS\u002FWSL) or `scripts\u002Fdoctor.ps1 [repo]` (Windows PowerShell). It reports OS, cores, load, the available tools, and an install command for each missing one.\n3. **Missing tools.** **Ask the user before installing anything.** Give the exact command for their OS (`references\u002Ftools-by-os.md`). Never run `sudo` or elevated installs yourself; ask the user to run them (in Claude Code: `! sudo apt-get install -y valgrind`). If they decline, fall back to the next metric on the ladder and say what precision you lost.\n4. **Repo conventions win.** Look for existing bench, profile, and trace tooling first (`bench`, `perf`, `profile`, `benchmark` scripts, tracing env flags, CI perf jobs) and reuse it. Repo instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) override this skill on run counts, memory caps, commit rules, and test commands.\n5. **Stack.** Open the matching section of `references\u002Fstacks.md` (web\u002Fbrowser, Node, Python, Go, Rust, JVM, .NET, native, mobile, databases\u002Fbackends, CI\u002Fbuilds, agent\u002FLLM workflows).\n6. **Drive the app.** Confirm you can reproduce and time the journey (a CLI command, an existing bench script, or browser tools). Automate repeated interactions when useful; a reproducible manual flow can suffice for a lean pass. Set up additional tooling only when the missing capability prevents a trustworthy result (ask before installing).\n\n| Verb in this skill | Claude Code | Codex \u002F OpenCode \u002F Gemini CLI \u002F Aider | Cursor \u002F Windsurf \u002F IDE agents | Chat only (no shell) |\n|---|---|---|---|---|\n| run a command | Bash (cap memory per repo rules) | shell tool | terminal tool | give command, user pastes output |\n| ask the user | AskUserQuestion, or ask in text | ask in chat | ask in chat | ask in chat |\n| browser counters | browser skill \u002F Playwright \u002F CDP | Playwright via shell | built-in browser or Playwright | snippet from `references\u002Fbrowser.md` pasted in DevTools |\n| parallel threads | subagents or workers, one journey each | separate sessions or worktrees | separate chats or branches | one journey at a time |\n| long-running wait | background task plus notification | blocking wait | terminal | user reports back |\n\n## 1. The loop\n\nRun one loop per **journey**: a user-visible flow with a start and an end, such as \"cold launch to typeable\", \"open conversation\", \"send to first token\", \"search request p50\", \"`index` on repo X\", or \"CI job wall time\".\n\n1. **Choose the journey.** After brief triage, name the journey, the user-visible endpoint, and the baseline. Keep implementation focused. A lean pass needs no separate thread or project artifact.\n2. **Build the benchmark.** Trace the real flow end to end and reproduce it with fixed inputs. In a lean pass, a scripted repro and a timer are enough. In deep mode, build a lab harness at a typical size *and* a worst-case size taken from real shapes (the longest real conversation, the biggest repo). Toy fixtures hide superlinear work. Record a baseline (section 3).\n3. **Find the dominant cost.** Profile; don't guess. Rank costs, and attack the biggest one the profile shows (section 4).\n4. **Make a coherent change, sized for risk.** Establish the affected behavior with existing tests or a targeted check before optimizing. Add regression tests where meaningful coverage is missing. Guard user-perceptible changes in proportion to risk (section 5).\n5. **Verify the result.** Re-run the same journey and affected behavior checks. Read comparable field data if already available; distinguish a lab win from a confirmed field win. Deployment and monitoring follow the user's authorized scope.\n6. **Protect valuable wins.** Reuse an existing gate or lower an existing ratchet ceiling. Add a new focused gate only when the same regression has already recurred or the user asks for one. Dedicated CI or nightly infrastructure belongs to explicitly requested deeper work.\n7. **Finish or continue.** Apply section 7 before another experiment. Deep mode permits further investigation within the requested journeys and budget; it does not remove stopping rules.\n\n## 2. The metric ladder\n\nUse three tiers. Each tier has a different job, so do not substitute one tier for another.\n\nA lean pass usually needs Truth and Explain: before\u002Fafter wall clock and a targeted trace or profile. Add a counter when it is a cheaper reliable way to compare experiments; add a new gate only under section 1, step 6. Using a diagnostic counter does not require CI integration. Validate proxies against wall clock before claiming a user-visible gain.\n\n| Tier | Purpose | Examples | Property |\n|---|---|---|---|\n| **Truth** | What users feel; the number you report | wall clock per journey, p50\u002Fp95 latency, time-to-interactive, frames per second, peak RSS | noisy, hardware-dependent |\n| **Gate** | CI ratchets, fast iteration, tiny diffs | instruction counts, function call counts, allocations\u002Fop, render commits, style recalcs, layouts, DOM mutations, DB queries, network requests, bytes | deterministic for fixed input; machine-independent or nearly so |\n| **Explain** | Why a number moved | CPU profile, call tree, flame graph, per-function call counts, query log, frame-by-frame trace | diagnostic, not gated |\n\nRules:\n\n- **Validate every gate proxy against truth** before trusting it. Make one real optimization and measure both the proxy and the wall clock. They must move in the same direction with a plausible ratio. In the sprint, cutting instructions by 48% cut wall clock by 78% on one hot path, and 31% fewer instructions gave 44% less wall clock on another. If the proxy moves and the wall clock does not, the proxy is measuring the wrong work. Pick another proxy. Validation covers one mechanism: re-check against wall clock whenever the kind of change, the workload, or the fixture changes, because a proxy can drop for work that was never on the slow path.\n- **Measure the noise of the gate.** Run it twice on unchanged code. Deterministic counts should agree within 0.1%; instruction counts under Valgrind with `node --predictable` typically agree within 0.001%. Set the ratchet tolerance just above the observed noise.\n- **Subtract fixed startup cost.** A process-level count includes runtime boot. For example, an empty `node` process costs about 96M instructions, which can hide a 40% workload win as a 3% total change. Either measure a no-op baseline and subtract it, or measure in-process around the journey.\n- **Count calls to explain instructions.** `scripts\u002Fcall-counts.mjs` showed a resolver called 59,999 times instead of 20,000: the \"resolve each ID once, not three times\" fix is visible directly.\n- **Pair every gate with a counter-check.** A count rewards deleting work, including the work that keeps the app correct: revalidation, cache invalidation, persistence, retries, syncing. Before removing a request, write, or render, prove it is redundant (a named invariant already guarantees its result). Add a check that fails if it wasn't: freshness after a change made elsewhere, durability across a refresh mid-action, convergence to server truth. Fewer requests with stale data on screen is a regression, not a win.\n- **Split at the ready mark, then identify the critical path.** Split each count at the journey's ready mark into *before ready* and *after ready*. Before-ready is only an upper bound on blocking work: analytics or a prefetch can start early without holding anything up. Use the trace to identify dependencies; where ambiguous, vary a request's delay and compare ready times (`references\u002Fbrowser.md`). A large artificial delay can create a bottleneck that was absent in the original run. Optimize observed blocking work first, usually by reordering: fetch what the first interaction needs first, then keep data fresh in the background. Background work still costs battery, data, and server load, but remove it only with the redundancy proof above.\n- **Ratchet absolute counts per journey, never global ratios.** Coverage percentages and averages can block deleting dead code. Deleting code should only ever lower a count.\n- **Count events, not scores.** A summed or averaged score can pass while users see a problem. Each sidebar shift in the sprint scored about 0.008 CLS, well inside the 0.1 \"good\" threshold, yet the page felt janky. Attribute raw entries (each layout shift, each long frame) to named regions, and fail on any where none is expected.\n- **Several cheap counters beat one perfect one.** Each new instrument tends to expose new targets. In the sprint, about a third of the PRs added telemetry or a guardrail.\n\n## 3. Measurement protocol\n\n### Wall clock (truth)\n\n- **Audit the window first.** Start at the user's action (the input event's timestamp or navigation start), not at component mount or request start. End when the user can use the result. Separate client time from server time. Check the instrumented number once against a screen recording: a dashboard that starts the clock late will \"prove\" a slow journey is fast.\n- Use `hyperfine --warmup 3 --runs 10 '\u003Ccmd>'`, or the stack-native harness (pyperf, `go test -bench` plus benchstat, criterion, JMH, BenchmarkDotNet).\n- Report **median of at least 3 runs** (more if the repo asks) and the spread (IQR or min\u002Fmax). Increase runs when noise could change the conclusion. Measure **peak memory** when the change trades memory for speed or memory is part of the complaint (`\u002Fusr\u002Fbin\u002Ftime -v` on Linux, `\u002Fusr\u002Fbin\u002Ftime -l` on macOS, process stats on Windows).\n- Record machine load (`uptime` or `doctor.sh`), core count, power mode, and whether the cache was warm or cold. Compare before and after only on the same machine, input, and load.\n- For cold-start journeys, state how you made the start cold: dropped OS caches, a fresh profile, or a cleared app cache.\n- Investigate tail percentiles when they are part of the complaint or requested deeper work; reuse field data where possible. For percentile estimates, aim for at least 10 observations beyond the percentile: about 200 runs for p95 and 1,000 for p99 as a starting point, not a precision guarantee. With 100 samples, p99 is just the slowest run or two. Report the distribution and uncertainty. A lean pass can report medians and spread without claiming p95\u002Fp99.\n- Always give absolute times next to percentages. \"−78%\" is very different at 60 ms and at 4 s.\n\n### Deterministic counts (gate)\n\n- **Instructions:** `scripts\u002Finstr-count.sh -- \u003Ccmd>`. It uses the Valgrind backend where available, then `perf stat` with a PMU, then macOS `time -l`. For Node, add `--predictable --random-seed=1`. Keep the workload small, because Valgrind is 20-80x slower.\n- **Calls:** `node scripts\u002Fcall-counts.mjs --filter \u003Csrc-dir> --json calls.json -- node \u003Centry>` for JS. For other stacks, see `references\u002Fstacks.md` (cProfile ncalls, Go pprof counts, callgrind call counts, JFR, EventPipe).\n- **UI work:** render commits, style recalculations, layouts, DOM mutations, long animation frames, and layout shifts per interaction (`references\u002Fbrowser.md`).\n- **I\u002FO work:** queries per request, rows\u002Fbuffers read, network requests and bytes per journey, file reads, cache misses, process spawns. These are often the biggest wins and the easiest gates.\n- **Agent\u002FLLM workflows:** tool calls, model round trips, input\u002Foutput tokens, and cache-hit ratio per task.\n\nWrite every gate into a single flat `metrics.json` (`{\"journey.metric\": number}`) so `ratchet.mjs` can check it.\n\n### Frame budget (smoothness)\n\nFor streaming, scrolling, and animation, use the target device's frame budget: 16.67 ms at 60 Hz and 8.33 ms at 120 Hz. Start with a recording and a rendering trace of the problematic interaction; examine long tasks and frame stalls. An FPS readout from `requestAnimationFrame` timestamps can help but does not prove frames were presented smoothly.\n\n**Deep mode, when needed:** drive a compatible headless Chromium rig with deterministic frame stepping (CDP `HeadlessExperimental.beginFrame`) and inspect the worst case frame by frame (`references\u002Fbrowser.md`). Verify that N begin frames produce N callbacks before relying on the rig. Virtual frame cadence alone does not prove real hardware meets its rendering budget; validate on a representative device. Gate on main-thread blocking and worst frame costs rather than average FPS. The sprint used this method to remove work growing with message length, memoize finished blocks, and move tokenization to a worker; it then retained the rig as a nightly job.\n\n## 4. Hunting: where the time actually goes\n\nChoose the **census** suggested by the profile; these are investigation options,\nnot a checklist to run in full. Each found a large, invisible cost in the sprint:\n\n- **Subscription\u002Fre-render census:** count components, hooks, store subscriptions, and listeners that wake on one keystroke or event. One composer had about 6,900 hooks and 900 subscriptions re-rendering per keystroke.\n- **Selector\u002Frule audit:** a single expensive CSS selector (`:root:has(...)`) added 24 ms to every DOM change. The same applies to regex tables, middleware chains, and validation rules.\n- **Code path tracing:** a forgotten `location.reload()` caused about 500k hidden reloads a day. Grep for reloads, retries, polling, and duplicate fetches.\n- **Idle profiling:** profile while the user does nothing. One idle tab cloned cache snapshots into IndexedDB twice a minute on the main thread.\n- **Data-flow census:** count fetches, cache reads and writes, and renders per journey. Repeated work, such as the same ID resolved three times, often traces back to one data-loading pattern that also triggers extra renders.\n- **Encoding and representation:** the sprint found that a character outside Latin-1 (an em dash or a curly quote, but not `é`, which fits) made the reply use V8's two-byte string representation and slowed its highlighting regexes. Copying eligible code blocks into one-byte strings cut a 1.0 s freeze to 0.35 s. Apply this only when profiling shows the same cost; preserve code points that require two bytes.\n- **Re-check against the budget after a micro-fix.** 0.35 s is still about 40 frames at 120 Hz. If the work is still over budget, ask whether it belongs on that thread at all. A worker or WASM module, lazy-loaded, takes it off the main thread entirely. Memoize its results per finished block on the calling side, so each new chunk does not re-run it over everything. Count the costs: bundle size, message passing, ordering, and cancellation.\n- **Style, paint, and GPU:** CPU profiles miss these costs. Count style recalcs and layouts via CDP, and use the DevTools Rendering panel (paint flashing, layout-shift regions, layer borders).\n- **Costs in a dependency.** When the profile points into a library, runtime, or browser, the fix may belong upstream; the sprint landed changes in Electron, Chromium, and Node. Ship a local workaround that links the upstream issue, and remove it once the fix is released.\n\n### Pattern catalogue\n\nUse the profile to select a candidate. Verify preserved behavior with existing\ntests or targeted equivalence checks; caches and scheduling changes also need\nfreshness, ordering, and interaction checks. More complex patterns must justify\ntheir setup and maintenance.\n\n| Smell | Fix |\n|---|---|\n| Same lookup repeated per item | resolve once and pass it down; hoist out of loops |\n| Plain objects used as dictionaries over many shapes (megamorphic lookups) | `Map`, or a stable shape; resolve once |\n| Expensive regex\u002Fparse on every line | cheap first-character or length prefilter, then the full check |\n| O(total length) work per streamed chunk | memoize finished blocks; only process the growing tail |\n| Heavy work on the UI\u002Fmain\u002Frequest thread | move it to a worker, thread pool, or background job; memoize results per finished unit; keep a fallback |\n| Big layout\u002Fpaint in one frame | split it across frames (cell by cell, row by row) to fit the budget |\n| Interactive UI waits for framework boot | ship a static shell rendered from the same component, then hydrate over it; test the handoff |\n| Recompiling the same code every start | bytecode or code cache, snapshot, AOT, persistent compile cache |\n| Navigation waits on fetch | prefetch on intent (hover, focus, viewport), with cancellation and a concurrency cap |\n| Persistent UI remounts on navigation | keep it mounted across routes (composer, sidebar) |\n| Page waits on the network for data it showed last time | render the cached copy immediately (provisional if needed), then revalidate and reconcile; never skip the revalidation |\n| Constant per-session work repeated per request | cache it behind a witness (hash, stat signature, frozen value identity); fall back when unsure |\n| N+1 queries or round trips | batch, join, or preload; gate on query count |\n| Re-render storms | narrow subscriptions, stable props, selector memoization; gate on commit count |\n| Late content moving the layout | reserve space, pin layout, gate on layout shifts per region; allow movement only where reconciliation changed the data |\n| Regions shown together resolve at different times | load them from the same cache or request, or hold the group and reveal it together; measure when the *last* one is usable |\n\n## 5. Guardrails: what makes bold changes safe\n\n- **Establish behavior first.** Reuse existing tests or a targeted reproduction before optimizing. Add tests for meaningful uncovered regression risks; a simple local change does not require a new test framework.\n- **Equivalence, not just speed.** Verify that output and behavior are preserved. Use differential fixtures when an algorithm, parser, or fast path changes; uncertain fast paths fall back. For subtle cache keys or witnesses, mutation-check that the test catches a broken key, then restore it. This extra check is justified by that failure risk, not required for every optimization.\n- **Hand-offs get their own tests.**\n  - Generate the fast copy from the source of truth, never by hand. The sprint rendered the real component in JSDOM to produce the static markup.\n  - Static-to-live UI swaps need layout comparisons across several viewport sizes (the sprint used 14 viewports with ±1 px tolerance), plus keystroke-ordering tests.\n  - Worker offloads need ordering and cancellation tests.\n  - Caches need invalidation tests.\n  - Where seam telemetry exists, investigate unexpected movement; add dedicated monitoring only when justified by risk and scope.\n- **Adversarial scenarios.** Users rarely report these failures, and speed metrics never show them. Select the scenarios affected by the change; freshness and durability remain required when those behaviors are touched:\n  - change or delete something in a second tab or device, then reload;\n  - refresh or navigate away mid-action (right after send);\n  - cold, warm, and stale caches;\n  - slow and offline networks;\n  - the worst-case fixture.\n- **Make human testing easy.** Use an existing preview URL or downloadable build, or give short reproduction steps. Add preview infrastructure only when its reuse justifies the cost. Build alternatives when a real interaction trade-off needs an owner's decision; otherwise implement the best-supported fix. Have the owner try perceptible interaction changes before rollout.\n- **Auto-merge only what gates cover.** Visual, animation, and interaction changes need a human to look at a before\u002Fafter recording, because no count covers them.\n- **Guard perceptible changes in proportion to risk.** Use what the project already has: a feature flag, a config or env switch, a release channel, or for a CLI or small tool, a plain revert. Where flags and staged rollout exist, roll out to the team, then to a small share of users, then to everyone. Classify each flag as a *kill switch* or a *ramp*, give it an owner and a removal date, keep all flags in one list, and retire them. The sprint created about 200 and retired more than half before it ended.\n- **Review.** Follow the project's review requirements. Show perceptible interaction changes as before\u002Fafter recordings where practical. Review the stated mechanism and counter-checks, not just the numbers, and turn consequential doubts into falsifiable checks (`references\u002Ffield-lessons.md` D7).\n- **Lab checks vs committed tests.** Generate as many throwaway checks as help you prove a change. Commit only the ones that guard a real invariant, within the repo's test budget.\n- **Ratchet valuable wins.** Reuse an existing gate. Add a new one only for a regression that has already recurred, or when the user asks for one.\n  - `scripts\u002Fratchet.mjs check` runs in CI or nightly.\n  - Post the result where agents and reviewers read it: `--markdown \"$GITHUB_STEP_SUMMARY\"`, or a file posted as a PR comment. The coding agent and the review agent then catch regressions before a human has to.\n  - `update` only ever lowers ceilings. Raising a ceiling must be a reviewed edit with a stated reason.\n- **Headless isn't the user's machine.** Headless browsers lack real browser UI, prerendering, extensions, and GPUs. A page can be rendered at one viewport size and shown at another: Chrome prerendered claude.ai at the new-tab page's height, and the page grew 56 px after first paint. When field data disagrees with the lab, reproduce the field condition in the lab and add it as a test.\n\n## 6. Deep mode: many narrow threads, not one wide one\n\nOnly for explicitly requested extended work, such as a sprint or exhaustive\noptimization across named journeys. Match the workflow to that request; one\ngate or one difficult bottleneck does not authorize every step below.\n\n- Run one journey or benchmark per thread or worker, and scale by opening more threads. The sprint ran 150+ in parallel.\n- Each thread has a named owner who supplies **taste**: which trade-offs are acceptable. The agent's job is to measure each option's cost (for example, a word-by-word fade's share of the frame budget) and build two or three variants. The owner chooses. Use data where it exists: pick a skeleton delay from the measured load-time distribution so the skeleton never flashes for a frame or two. Holding content back until it is complete makes rendering cheaper but delays the first thing users see, so that is a taste call, not a rule.\n- A coordinator supplies **direction**: sequencing, deduplication, merging threads that step on each other, and closing threads at diminishing returns.\n- Supply **ambition**: agents default to small scope. Push for boldness only once the guardrails in section 5 are in place; the sprint asked for it because it trusted them.\n  - Continue beyond an initial target only when the requested project includes further optimization; respect explicit stopping limits and the complexity budget.\n  - When wins plateau, propose three options, from incremental to radical (a cache layer, a worker or process boundary, a new data model, a different runtime). Give each an estimated time saved, its complexity, and the benchmark that would prove it. Implement the one the owner picks.\n  - A standing instruction beats repeated nudges, for example in `AGENTS.md` or `CLAUDE.md`: \"If I state the outcome, keep going and hill climb until you get there.\" Repo rules on scope and approval still win.\n- **Estimate impact in milliseconds, not effort in days.** Agents estimate effort in human working days and overshoot badly. Within the authorized scope, do the work now instead of scheduling it.\n- Where possible, run agent-driven browsers and wall-clock benchmarks on a separate machine, VM, or container, so the user's activity stays out of the numbers and the agent stays off their screen.\n- On a single machine, keep heavy measurements serial. Parallel benchmarks corrupt each other's wall clock. Deterministic counts are safer to parallelize.\n\n## 7. When to stop\n\nRank benefit by **absolute time saved × how often the journey runs**, accounting\nfor affected users and devices when known. For responsiveness, also consider\nfreezes and interaction delays. Weigh that benefit and confidence against the\n**total cost**: investigation, implementation, verification, and maintenance.\nAvoid a precise score when frequency or effort is unknown.\n\nStop when any of these is true:\n\n- **Target met:** the user's target, or the provisional one stated in the lean pass, is met, affected behavior is verified, and no further improvement is both clear and inexpensive;\n- the next win is below the measurement noise or below what users can perceive;\n- the complexity cost is greater than the gain. In one sprint decision, saving 2 ms per send did not justify maintaining a 900-line custom build plugin. New infrastructure needs a perceptible win.\n\nWhenever stopping below the target, report the shortfall and why. If the next\nstep requires material scope expansion, explain the evidence for that step;\ndo not claim the target was achieved.\nBelow the target, do not stop after a token win while a clear bottleneck remains\nwithin scope. Do not start fresh investigations merely to populate a backlog.\nReport only significant remaining issues already observed, with uncertainty.\nIn deep mode, open another thread only for a requested journey and within the\nagreed scope and budget.\n\n## 8. Report format\n\nLead with the result, and put the command log at the end.\n\nFor a lean pass, report the journey and input, before\u002Fafter median, run count, and spread,\nthe cause and change, the behavior checks and results, and why work finished.\nInclude an unmet target or significant remaining limitation. Omit unused gates,\nflags, mutation checks, ratchets, and unavailable frequency estimates.\n\nFor deeper work, use the relevant fields below:\n\n```\nJourney: \u003Cname> (\u003Cplatform>, \u003Cinput\u002Ffixture>, cold|warm)\nTruth:   \u003Cbefore median> -> \u003Cafter median>  (\u003Cx>x, n=\u003Cruns>, spread \u003CIQR>, peak RSS \u003Ca> -> \u003Cb>)\nImpact:  \u003Cms saved> x \u003Cjourney frequency> ; before\u002Fafter-ready split and proven blocking items if relevant\nGates:   instructions \u003Ca> -> \u003Cb> (\u003C-%>), calls \u003Ca> -> \u003Cb>, \u003Cother counts>\nProxy validated: \u003Cyes: proxy -% vs wall -%> | \u003Cno: why>\nCause:   \u003Cdominant cost from profile, file:line>\nChange:  \u003Cwhat changed>; flag \u003Cname> | none\nSafety:  \u003Cequivalence\u002Fdifferential test>, \u003Cmutation check result>\nCounter: \u003Cfreshness \u002F durability \u002F scenario checks that prove nothing necessary was removed>\nRatchet: \u003Cbaseline file> lowered: \u003Cmetric> \u003Cold> -> \u003Cnew>\nCommand: \u003Cexact commands used> ; machine \u003Ccores, load>\n```\n\nWhen summarizing several journeys, use the geometric mean of the speedups, not the arithmetic mean.\n\n## Files\n\n- `scripts\u002Fdoctor.sh`, `scripts\u002Fdoctor.ps1`: detect OS, stack, and tools, and print install commands. They never install.\n- `scripts\u002Finstr-count.sh`: instruction counts (valgrind | perf | macOS backends).\n- `scripts\u002Fcall-counts.mjs`: deterministic JS function call counts via V8 precise coverage.\n- `scripts\u002Fratchet.mjs`: `check` \u002F `update` ceilings that only go down; `--markdown FILE` for CI summaries and PR comments.\n- `references\u002Ftools-by-os.md`: tool matrix and install commands for Linux, macOS, Windows, and WSL.\n- `references\u002Fstacks.md`: recipes per stack and workflow (truth, gate, and explain tools for each).\n- `references\u002Fbrowser.md`: in-page counters (commits, style recalcs, DOM mutations, layout shifts, requests before and after ready, a delay test for blocking requests, frame meter), cache and freshness tests, and CDP frame stepping.\n- `references\u002Ffield-lessons.md`: claims in the sprint write-up, the main public critique, and verdicts on what holds up. Read relevant entries when a proposed optimization touches those mechanisms, especially when removing cache, sync, or persistence work.\n","# ProvenFast\n\n> If it can be measured, it can be improved. Once a metric exists, an agent can\n> iterate against it without waiting for field data.\n\nDistilled from Anthropic's August 2026 claude.ai speed sprint\n(\u003Chttps:\u002F\u002Fclaude.dev\u002Fblog\u002Fhow-we-made-claude-ai-faster\u002F>). In that sprint, an\nagent working in one shared channel made the core journeys 3.1x faster\n(geometric mean across 13 metrics) in two weeks. Anthropic reports 3,000+\nmerged changes without a single customer-facing incident or rollback. That is\ntheir claim, and a critic later found UX bugs it does not capture\n(`references\u002Ffield-lessons.md` B1). The useful part is not any single trick but\nthe **loop**, the **metric ladder**, and the **guardrails** below. They work for\nany stack.\n\n## Default: the most improvement for the least effort\n\nDeliver the largest practical improvement to ordinary users for a proportionate\ntotal cost (section 7). Unless the user explicitly\nasks for deeper work, run the **lean pass**:\n\nKeep a normal invocation bounded to the current task. Complete worthwhile fixes\nand verification, then return the result; ongoing optimization is separate work.\n\n1. **Triage briefly, then focus.** If the user names a slow interaction, start there. For a broad request, briefly inspect startup, navigation, and the main interaction using available timings or traces, then select the largest worthwhile bottleneck. Measure on a representative device and input, including a realistic large input when size affects the cost. Use the user's target; if there is none, state a provisional target grounded in the baseline and the observed pain, and proceed.\n2. **Measure lightly.** Before\u002Fafter wall clock (median of at least 3 runs) and a targeted trace or profile are usually enough. Add measurement only when it resolves uncertainty or makes the next experiment cheaper.\n3. **Fix the dominant cost with proportionate effort.** Prefer existing tools and simple changes: fewer duplicate fetches, narrower re-renders, smaller payloads, startup work deferred, better data loading (catalogue in section 4). A larger bounded change, such as moving parsing to a worker, can be the efficient choice if it removes the main bottleneck. Weigh user benefit against total cost (section 7); line count alone does not decide.\n4. **Verify what the change could break.** Run the affected tests. When the change touches caching, fetching, or saving, check freshness and persistence (section 5). Scale verification to risk.\n5. **Stop at the target** (section 7). The target is the user's, or the provisional one from step 1; meet it, then finish. Past the target, continue only while another improvement is both clear (the profile shows it) and inexpensive (a small change with existing tools). Avoid repeated searches for tiny gains. Report the measured result and any significant remaining bottleneck; label unmeasured gains as estimates or unknown.\n\n**Deep mode** needs an explicit request for an extended performance project: exhaustive investigation, specialized benchmark infrastructure, runtime replacement, or ongoing deploy monitoring. A broad app request permits brief triage of several journeys. A lean pass may reuse an existing counter, gate, or rollout mechanism. It adds a new regression gate only when the same regression has already recurred or the user asks for one. A request for one gate authorizes that gate, not a sprint. Material scope expansion still needs agreement.\n\nThe rest of this file is a toolbox for both modes. Read only relevant references,\nand use only the measurements and safeguards justified by the selected change.\nSteps marked *deep mode* apply only to the requested deeper work.\n\n## 0. Adapt before you measure\n\nDo this once per task, only as far as the journey needs. It decides which tools and which section of the references apply.\n\n1. **Harness.** Map the verbs in this skill to your tools (table below). If you cannot run commands, produce the exact commands and ask the user to run them and paste the output.\n2. **System.** If the environment or available tools are unclear, run `scripts\u002Fdoctor.sh [repo]` (Linux\u002FmacOS\u002FWSL) or `scripts\u002Fdoctor.ps1 [repo]` (Windows PowerShell). It reports OS, cores, load, the available tools, and an install command for each missing one.\n3. **Missing tools.** **Ask the user before installing anything.** Give the exact command for their OS (`references\u002Ftools-by-os.md`). Never run `sudo` or elevated installs yourself; ask the user to run them (in Claude Code: `! sudo apt-get install -y valgrind`). If they decline, fall back to the next metric on the ladder and say what precision you lost.\n4. **Repo conventions win.** Look for existing bench, profile, and trace tooling first (`bench`, `perf`, `profile`, `benchmark` scripts, tracing env flags, CI perf jobs) and reuse it. Repo instructions (AGENTS.md, CLAUDE.md, CONTRIBUTING) override this skill on run counts, memory caps, commit rules, and test commands.\n5. **Stack.** Open the matching section of `references\u002Fstacks.md` (web\u002Fbrowser, Node, Python, Go, Rust, JVM, .NET, native, mobile, databases\u002Fbackends, CI\u002Fbuilds, agent\u002FLLM workflows).\n6. **Drive the app.** Confirm you can reproduce and time the journey (a CLI command, an existing bench script, or browser tools). Automate repeated interactions when useful; a reproducible manual flow can suffice for a lean pass. Set up additional tooling only when the missing capability prevents a trustworthy result (ask before installing).\n\n| Verb in this skill | Claude Code | Codex \u002F OpenCode \u002F Gemini CLI \u002F Aider | Cursor \u002F Windsurf \u002F IDE agents | Chat only (no shell) |\n|---|---|---|---|---|\n| run a command | Bash (cap memory per repo rules) | shell tool | terminal tool | give command, user pastes output |\n| ask the user | AskUserQuestion, or ask in text | ask in chat | ask in chat | ask in chat |\n| browser counters | browser skill \u002F Playwright \u002F CDP | Playwright via shell | built-in browser or Playwright | snippet from `references\u002Fbrowser.md` pasted in DevTools |\n| parallel threads | subagents or workers, one journey each | separate sessions or worktrees | separate chats or branches | one journey at a time |\n| long-running wait | background task plus notification | blocking wait | terminal | user reports back |\n\n## 1. The loop\n\nRun one loop per **journey**: a user-visible flow with a start and an end, such as \"cold launch to typeable\", \"open conversation\", \"send to first token\", \"search request p50\", \"`index` on repo X\", or \"CI job wall time\".\n\n1. **Choose the journey.** After brief triage, name the journey, the user-visible endpoint, and the baseline. Keep implementation focused. A lean pass needs no separate thread or project artifact.\n2. **Build the benchmark.** Trace the real flow end to end and reproduce it with fixed inputs. In a lean pass, a scripted repro and a timer are enough. In deep mode, build a lab harness at a typical size *and* a worst-case size taken from real shapes (the longest real conversation, the biggest repo). Toy fixtures hide superlinear work. Record a baseline (section 3).\n3. **Find the dominant cost.** Profile; don't guess. Rank costs, and attack the biggest one the profile shows (section 4).\n4. **Make a coherent change, sized for risk.** Establish the affected behavior with existing tests or a targeted check before optimizing. Add regression tests where meaningful coverage is missing. Guard user-perceptible changes in proportion to risk (section 5).\n5. **Verify the result.** Re-run the same journey and affected behavior checks. Read comparable field data if already available; distinguish a lab win from a confirmed field win. Deployment and monitoring follow the user's authorized scope.\n6. **Protect valuable wins.** Reuse an existing gate or lower an existing ratchet ceiling. Add a new focused gate only when the same regression has already recurred or the user asks for one. Dedicated CI or nightly infrastructure belongs to explicitly requested deeper work.\n7. **Finish or continue.** Apply section 7 before another experiment. Deep mode permits further investigation within the requested journeys and budget; it does not remove stopping rules.\n\n## 2. The metric ladder\n\nUse three tiers. Each tier has a different job, so do not substitute one tier for another.\n\nA lean pass usually needs Truth and Explain: before\u002Fafter wall clock and a targeted trace or profile. Add a counter when it is a cheaper reliable way to compare experiments; add a new gate only under section 1, step 6. Using a diagnostic counter does not require CI integration. Validate proxies against wall clock before claiming a user-visible gain.\n\n| Tier | Purpose | Examples | Property |\n|---|---|---|---|\n| **Truth** | What users feel; the number you report | wall clock per journey, p50\u002Fp95 latency, time-to-interactive, frames per second, peak RSS | noisy, hardware-dependent |\n| **Gate** | CI ratchets, fast iteration, tiny diffs | instruction counts, function call counts, allocations\u002Fop, render commits, style recalcs, layouts, DOM mutations, DB queries, network requests, bytes | deterministic for fixed input; machine-independent or nearly so |\n| **Explain** | Why a number moved | CPU profile, call tree, flame graph, per-function call counts, query log, frame-by-frame trace | diagnostic, not gated |\n\nRules:\n\n- **Validate every gate proxy against truth** before trusting it. Make one real optimization and measure both the proxy and the wall clock. They must move in the same direction with a plausible ratio. In the sprint, cutting instructions by 48% cut wall clock by 78% on one hot path, and 31% fewer instructions gave 44% less wall clock on another. If the proxy moves and the wall clock does not, the proxy is measuring the wrong work. Pick another proxy. Validation covers one mechanism: re-check against wall clock whenever the kind of change, the workload, or the fixture changes, because a proxy can drop for work that was never on the slow path.\n- **Measure the noise of the gate.** Run it twice on unchanged code. Deterministic counts should agree within 0.1%; instruction counts under Valgrind with `node --predictable` typically agree within 0.001%. Set the ratchet tolerance just above the observed noise.\n- **Subtract fixed startup cost.** A process-level count includes runtime boot. For example, an empty `node` process costs about 96M instructions, which can hide a 40% workload win as a 3% total change. Either measure a no-op baseline and subtract it, or measure in-process around the journey.\n- **Count calls to explain instructions.** `scripts\u002Fcall-counts.mjs` showed a resolver called 59,999 times instead of 20,000: the \"resolve each ID once, not three times\" fix is visible directly.\n- **Pair every gate with a counter-check.** A count rewards deleting work, including the work that keeps the app correct: revalidation, cache invalidation, persistence, retries, syncing. Before removing a request, write, or render, prove it is redundant (a named invariant already guarantees its result). Add a check that fails if it wasn't: freshness after a change made elsewhere, durability across a refresh mid-action, convergence to server truth. Fewer requests with stale data on screen is a regression, not a win.\n- **Split at the ready mark, then identify the critical path.** Split each count at the journey's ready mark into *before ready* and *after ready*. Before-ready is only an upper bound on blocking work: analytics or a prefetch can start early without holding anything up. Use the trace to identify dependencies; where ambiguous, vary a request's delay and compare ready times (`references\u002Fbrowser.md`). A large artificial delay can create a bottleneck that was absent in the original run. Optimize observed blocking work first, usually by reordering: fetch what the first interaction needs first, then keep data fresh in the background. Background work still costs battery, data, and server load, but remove it only with the redundancy proof above.\n- **Ratchet absolute counts per journey, never global ratios.** Coverage percentages and averages can block deleting dead code. Deleting code should only ever lower a count.\n- **Count events, not scores.** A summed or averaged score can pass while users see a problem. Each sidebar shift in the sprint scored about 0.008 CLS, well inside the 0.1 \"good\" threshold, yet the page felt janky. Attribute raw entries (each layout shift, each long frame) to named regions, and fail on any where none is expected.\n- **Several cheap counters beat one perfect one.** Each new instrument tends to expose new targets. In the sprint, about a third of the PRs added telemetry or a guardrail.\n\n## 3. Measurement protocol\n\n### Wall clock (truth)\n\n- **Audit the window first.** Start at the user's action (the input event's timestamp or navigation start), not at component mount or request start. End when the user can use the result. Separate client time from server time. Check the instrumented number once against a screen recording: a dashboard that starts the clock late will \"prove\" a slow journey is fast.\n- Use `hyperfine --warmup 3 --runs 10 '\u003Ccmd>'`, or the stack-native harness (pyperf, `go test -bench` plus benchstat, criterion, JMH, BenchmarkDotNet).\n- Report **median of at least 3 runs** (more if the repo asks) and the spread (IQR or min\u002Fmax). Increase runs when noise could change the conclusion. Measure **peak memory** when the change trades memory for speed or memory is part of the complaint (`\u002Fusr\u002Fbin\u002Ftime -v` on Linux, `\u002Fusr\u002Fbin\u002Ftime -l` on macOS, process stats on Windows).\n- Record machine load (`uptime` or `doctor.sh`), core count, power mode, and whether the cache was warm or cold. Compare before and after only on the same machine, input, and load.\n- For cold-start journeys, state how you made the start cold: dropped OS caches, a fresh profile, or a cleared app cache.\n- Investigate tail percentiles when they are part of the complaint or requested deeper work; reuse field data where possible. For percentile estimates, aim for at least 10 observations beyond the percentile: about 200 runs for p95 and 1,000 for p99 as a starting point, not a precision guarantee. With 100 samples, p99 is just the slowest run or two. Report the distribution and uncertainty. A lean pass can report medians and spread without claiming p95\u002Fp99.\n- Always give absolute times next to percentages. \"−78%\" is very different at 60 ms and at 4 s.\n\n### Deterministic counts (gate)\n\n- **Instructions:** `scripts\u002Finstr-count.sh -- \u003Ccmd>`. It uses the Valgrind backend where available, then `perf stat` with a PMU, then macOS `time -l`. For Node, add `--predictable --random-seed=1`. Keep the workload small, because Valgrind is 20-80x slower.\n- **Calls:** `node scripts\u002Fcall-counts.mjs --filter \u003Csrc-dir> --json calls.json -- node \u003Centry>` for JS. For other stacks, see `references\u002Fstacks.md` (cProfile ncalls, Go pprof counts, callgrind call counts, JFR, EventPipe).\n- **UI work:** render commits, style recalculations, layouts, DOM mutations, long animation frames, and layout shifts per interaction (`references\u002Fbrowser.md`).\n- **I\u002FO work:** queries per request, rows\u002Fbuffers read, network requests and bytes per journey, file reads, cache misses, process spawns. These are often the biggest wins and the easiest gates.\n- **Agent\u002FLLM workflows:** tool calls, model round trips, input\u002Foutput tokens, and cache-hit ratio per task.\n\nWrite every gate into a single flat `metrics.json` (`{\"journey.metric\": number}`) so `ratchet.mjs` can check it.\n\n### Frame budget (smoothness)\n\nFor streaming, scrolling, and animation, use the target device's frame budget: 16.67 ms at 60 Hz and 8.33 ms at 120 Hz. Start with a recording and a rendering trace of the problematic interaction; examine long tasks and frame stalls. An FPS readout from `requestAnimationFrame` timestamps can help but does not prove frames were presented smoothly.\n\n**Deep mode, when needed:** drive a compatible headless Chromium rig with deterministic frame stepping (CDP `HeadlessExperimental.beginFrame`) and inspect the worst case frame by frame (`references\u002Fbrowser.md`). Verify that N begin frames produce N callbacks before relying on the rig. Virtual frame cadence alone does not prove real hardware meets its rendering budget; validate on a representative device. Gate on main-thread blocking and worst frame costs rather than average FPS. The sprint used this method to remove work growing with message length, memoize finished blocks, and move tokenization to a worker; it then retained the rig as a nightly job.\n\n## 4. Hunting: where the time actually goes\n\nChoose the **census** suggested by the profile; these are investigation options,\nnot a checklist to run in full. Each found a large, invisible cost in the sprint:\n\n- **Subscription\u002Fre-render census:** count components, hooks, store subscriptions, and listeners that wake on one keystroke or event. One composer had about 6,900 hooks and 900 subscriptions re-rendering per keystroke.\n- **Selector\u002Frule audit:** a single expensive CSS selector (`:root:has(...)`) added 24 ms to every DOM change. The same applies to regex tables, middleware chains, and validation rules.\n- **Code path tracing:** a forgotten `location.reload()` caused about 500k hidden reloads a day. Grep for reloads, retries, polling, and duplicate fetches.\n- **Idle profiling:** profile while the user does nothing. One idle tab cloned cache snapshots into IndexedDB twice a minute on the main thread.\n- **Data-flow census:** count fetches, cache reads and writes, and renders per journey. Repeated work, such as the same ID resolved three times, often traces back to one data-loading pattern that also triggers extra renders.\n- **Encoding and representation:** the sprint found that a character outside Latin-1 (an em dash or a curly quote, but not `é`, which fits) made the reply use V8's two-byte string representation and slowed its highlighting regexes. Copying eligible code blocks into one-byte strings cut a 1.0 s freeze to 0.35 s. Apply this only when profiling shows the same cost; preserve code points that require two bytes.\n- **Re-check against the budget after a micro-fix.** 0.35 s is still about 40 frames at 120 Hz. If the work is still over budget, ask whether it belongs on that thread at all. A worker or WASM module, lazy-loaded, takes it off the main thread entirely. Memoize its results per finished block on the calling side, so each new chunk does not re-run it over everything. Count the costs: bundle size, message passing, ordering, and cancellation.\n- **Style, paint, and GPU:** CPU profiles miss these costs. Count style recalcs and layouts via CDP, and use the DevTools Rendering panel (paint flashing, layout-shift regions, layer borders).\n- **Costs in a dependency.** When the profile points into a library, runtime, or browser, the fix may belong upstream; the sprint landed changes in Electron, Chromium, and Node. Ship a local workaround that links the upstream issue, and remove it once the fix is released.\n\n### Pattern catalogue\n\nUse the profile to select a candidate. Verify preserved behavior with existing\ntests or targeted equivalence checks; caches and scheduling changes also need\nfreshness, ordering, and interaction checks. More complex patterns must justify\ntheir setup and maintenance.\n\n| Smell | Fix |\n|---|---|\n| Same lookup repeated per item | resolve once and pass it down; hoist out of loops |\n| Plain objects used as dictionaries over many shapes (megamorphic lookups) | `Map`, or a stable shape; resolve once |\n| Expensive regex\u002Fparse on every line | cheap first-character or length prefilter, then the full check |\n| O(total length) work per streamed chunk | memoize finished blocks; only process the growing tail |\n| Heavy work on the UI\u002Fmain\u002Frequest thread | move it to a worker, thread pool, or background job; memoize results per finished unit; keep a fallback |\n| Big layout\u002Fpaint in one frame | split it across frames (cell by cell, row by row) to fit the budget |\n| Interactive UI waits for framework boot | ship a static shell rendered from the same component, then hydrate over it; test the handoff |\n| Recompiling the same code every start | bytecode or code cache, snapshot, AOT, persistent compile cache |\n| Navigation waits on fetch | prefetch on intent (hover, focus, viewport), with cancellation and a concurrency cap |\n| Persistent UI remounts on navigation | keep it mounted across routes (composer, sidebar) |\n| Page waits on the network for data it showed last time | render the cached copy immediately (provisional if needed), then revalidate and reconcile; never skip the revalidation |\n| Constant per-session work repeated per request | cache it behind a witness (hash, stat signature, frozen value identity); fall back when unsure |\n| N+1 queries or round trips | batch, join, or preload; gate on query count |\n| Re-render storms | narrow subscriptions, stable props, selector memoization; gate on commit count |\n| Late content moving the layout | reserve space, pin layout, gate on layout shifts per region; allow movement only where reconciliation changed the data |\n| Regions shown together resolve at different times | load them from the same cache or request, or hold the group and reveal it together; measure when the *last* one is usable |\n\n## 5. Guardrails: what makes bold changes safe\n\n- **Establish behavior first.** Reuse existing tests or a targeted reproduction before optimizing. Add tests for meaningful uncovered regression risks; a simple local change does not require a new test framework.\n- **Equivalence, not just speed.** Verify that output and behavior are preserved. Use differential fixtures when an algorithm, parser, or fast path changes; uncertain fast paths fall back. For subtle cache keys or witnesses, mutation-check that the test catches a broken key, then restore it. This extra check is justified by that failure risk, not required for every optimization.\n- **Hand-offs get their own tests.**\n  - Generate the fast copy from the source of truth, never by hand. The sprint rendered the real component in JSDOM to produce the static markup.\n  - Static-to-live UI swaps need layout comparisons across several viewport sizes (the sprint used 14 viewports with ±1 px tolerance), plus keystroke-ordering tests.\n  - Worker offloads need ordering and cancellation tests.\n  - Caches need invalidation tests.\n  - Where seam telemetry exists, investigate unexpected movement; add dedicated monitoring only when justified by risk and scope.\n- **Adversarial scenarios.** Users rarely report these failures, and speed metrics never show them. Select the scenarios affected by the change; freshness and durability remain required when those behaviors are touched:\n  - change or delete something in a second tab or device, then reload;\n  - refresh or navigate away mid-action (right after send);\n  - cold, warm, and stale caches;\n  - slow and offline networks;\n  - the worst-case fixture.\n- **Make human testing easy.** Use an existing preview URL or downloadable build, or give short reproduction steps. Add preview infrastructure only when its reuse justifies the cost. Build alternatives when a real interaction trade-off needs an owner's decision; otherwise implement the best-supported fix. Have the owner try perceptible interaction changes before rollout.\n- **Auto-merge only what gates cover.** Visual, animation, and interaction changes need a human to look at a before\u002Fafter recording, because no count covers them.\n- **Guard perceptible changes in proportion to risk.** Use what the project already has: a feature flag, a config or env switch, a release channel, or for a CLI or small tool, a plain revert. Where flags and staged rollout exist, roll out to the team, then to a small share of users, then to everyone. Classify each flag as a *kill switch* or a *ramp*, give it an owner and a removal date, keep all flags in one list, and retire them. The sprint created about 200 and retired more than half before it ended.\n- **Review.** Follow the project's review requirements. Show perceptible interaction changes as before\u002Fafter recordings where practical. Review the stated mechanism and counter-checks, not just the numbers, and turn consequential doubts into falsifiable checks (`references\u002Ffield-lessons.md` D7).\n- **Lab checks vs committed tests.** Generate as many throwaway checks as help you prove a change. Commit only the ones that guard a real invariant, within the repo's test budget.\n- **Ratchet valuable wins.** Reuse an existing gate. Add a new one only for a regression that has already recurred, or when the user asks for one.\n  - `scripts\u002Fratchet.mjs check` runs in CI or nightly.\n  - Post the result where agents and reviewers read it: `--markdown \"$GITHUB_STEP_SUMMARY\"`, or a file posted as a PR comment. The coding agent and the review agent then catch regressions before a human has to.\n  - `update` only ever lowers ceilings. Raising a ceiling must be a reviewed edit with a stated reason.\n- **Headless isn't the user's machine.** Headless browsers lack real browser UI, prerendering, extensions, and GPUs. A page can be rendered at one viewport size and shown at another: Chrome prerendered claude.ai at the new-tab page's height, and the page grew 56 px after first paint. When field data disagrees with the lab, reproduce the field condition in the lab and add it as a test.\n\n## 6. Deep mode: many narrow threads, not one wide one\n\nOnly for explicitly requested extended work, such as a sprint or exhaustive\noptimization across named journeys. Match the workflow to that request; one\ngate or one difficult bottleneck does not authorize every step below.\n\n- Run one journey or benchmark per thread or worker, and scale by opening more threads. The sprint ran 150+ in parallel.\n- Each thread has a named owner who supplies **taste**: which trade-offs are acceptable. The agent's job is to measure each option's cost (for example, a word-by-word fade's share of the frame budget) and build two or three variants. The owner chooses. Use data where it exists: pick a skeleton delay from the measured load-time distribution so the skeleton never flashes for a frame or two. Holding content back until it is complete makes rendering cheaper but delays the first thing users see, so that is a taste call, not a rule.\n- A coordinator supplies **direction**: sequencing, deduplication, merging threads that step on each other, and closing threads at diminishing returns.\n- Supply **ambition**: agents default to small scope. Push for boldness only once the guardrails in section 5 are in place; the sprint asked for it because it trusted them.\n  - Continue beyond an initial target only when the requested project includes further optimization; respect explicit stopping limits and the complexity budget.\n  - When wins plateau, propose three options, from incremental to radical (a cache layer, a worker or process boundary, a new data model, a different runtime). Give each an estimated time saved, its complexity, and the benchmark that would prove it. Implement the one the owner picks.\n  - A standing instruction beats repeated nudges, for example in `AGENTS.md` or `CLAUDE.md`: \"If I state the outcome, keep going and hill climb until you get there.\" Repo rules on scope and approval still win.\n- **Estimate impact in milliseconds, not effort in days.** Agents estimate effort in human working days and overshoot badly. Within the authorized scope, do the work now instead of scheduling it.\n- Where possible, run agent-driven browsers and wall-clock benchmarks on a separate machine, VM, or container, so the user's activity stays out of the numbers and the agent stays off their screen.\n- On a single machine, keep heavy measurements serial. Parallel benchmarks corrupt each other's wall clock. Deterministic counts are safer to parallelize.\n\n## 7. When to stop\n\nRank benefit by **absolute time saved × how often the journey runs**, accounting\nfor affected users and devices when known. For responsiveness, also consider\nfreezes and interaction delays. Weigh that benefit and confidence against the\n**total cost**: investigation, implementation, verification, and maintenance.\nAvoid a precise score when frequency or effort is unknown.\n\nStop when any of these is true:\n\n- **Target met:** the user's target, or the provisional one stated in the lean pass, is met, affected behavior is verified, and no further improvement is both clear and inexpensive;\n- the next win is below the measurement noise or below what users can perceive;\n- the complexity cost is greater than the gain. In one sprint decision, saving 2 ms per send did not justify maintaining a 900-line custom build plugin. New infrastructure needs a perceptible win.\n\nWhenever stopping below the target, report the shortfall and why. If the next\nstep requires material scope expansion, explain the evidence for that step;\ndo not claim the target was achieved.\nBelow the target, do not stop after a token win while a clear bottleneck remains\nwithin scope. Do not start fresh investigations merely to populate a backlog.\nReport only significant remaining issues already observed, with uncertainty.\nIn deep mode, open another thread only for a requested journey and within the\nagreed scope and budget.\n\n## 8. Report format\n\nLead with the result, and put the command log at the end.\n\nFor a lean pass, report the journey and input, before\u002Fafter median, run count, and spread,\nthe cause and change, the behavior checks and results, and why work finished.\nInclude an unmet target or significant remaining limitation. Omit unused gates,\nflags, mutation checks, ratchets, and unavailable frequency estimates.\n\nFor deeper work, use the relevant fields below:\n\n```\nJourney: \u003Cname> (\u003Cplatform>, \u003Cinput\u002Ffixture>, cold|warm)\nTruth:   \u003Cbefore median> -> \u003Cafter median>  (\u003Cx>x, n=\u003Cruns>, spread \u003CIQR>, peak RSS \u003Ca> -> \u003Cb>)\nImpact:  \u003Cms saved> x \u003Cjourney frequency> ; before\u002Fafter-ready split and proven blocking items if relevant\nGates:   instructions \u003Ca> -> \u003Cb> (\u003C-%>), calls \u003Ca> -> \u003Cb>, \u003Cother counts>\nProxy validated: \u003Cyes: proxy -% vs wall -%> | \u003Cno: why>\nCause:   \u003Cdominant cost from profile, file:line>\nChange:  \u003Cwhat changed>; flag \u003Cname> | none\nSafety:  \u003Cequivalence\u002Fdifferential test>, \u003Cmutation check result>\nCounter: \u003Cfreshness \u002F durability \u002F scenario checks that prove nothing necessary was removed>\nRatchet: \u003Cbaseline file> lowered: \u003Cmetric> \u003Cold> -> \u003Cnew>\nCommand: \u003Cexact commands used> ; machine \u003Ccores, load>\n```\n\nWhen summarizing several journeys, use the geometric mean of the speedups, not the arithmetic mean.\n\n## Files\n\n- `scripts\u002Fdoctor.sh`, `scripts\u002Fdoctor.ps1`: detect OS, stack, and tools, and print install commands. They never install.\n- `scripts\u002Finstr-count.sh`: instruction counts (valgrind | perf | macOS backends).\n- `scripts\u002Fcall-counts.mjs`: deterministic JS function call counts via V8 precise coverage.\n- `scripts\u002Fratchet.mjs`: `check` \u002F `update` ceilings that only go down; `--markdown FILE` for CI summaries and PR comments.\n- `references\u002Ftools-by-os.md`: tool matrix and install commands for Linux, macOS, Windows, and WSL.\n- `references\u002Fstacks.md`: recipes per stack and workflow (truth, gate, and explain tools for each).\n- `references\u002Fbrowser.md`: in-page counters (commits, style recalcs, DOM mutations, layout shifts, requests before and after ready, a delay test for blocking requests, frame meter), cache and freshness tests, and CDP frame stepping.\n- `references\u002Ffield-lessons.md`: claims in the sprint write-up, the main public critique, and verdicts on what holds up. Read relevant entries when a proposed optimization touches those mechanisms, especially when removing cache, sync, or persistence work.\n",{"name":5,"description":7},"main","59ee67804bc373a9bd079a3a27f47277a6efe564","skill-library\u002Fpacks\u002Factive\u002Fprovenfast","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness","https:\u002F\u002Fgithub.com\u002Fham-zax","2026-11-15 01:18:51",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add ham-zax\u002Fwebharness --skill provenfast",{"tool":36,"command":37},"bunx","bunx skills add ham-zax\u002Fwebharness --skill provenfast",{"tool":39,"command":40},"pnpm","pnpm dlx skills add ham-zax\u002Fwebharness --skill provenfast","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002FSKILL.md",true,[44,50,54,58,62,68,72,76,80],{"path":45,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":48,"sourceHtmlUrl":49},"references\u002Fbrowser.md","REFERENCE","参考文档",10719,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Freferences\u002Fbrowser.md",{"path":51,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":52,"sourceHtmlUrl":53},"references\u002Ffield-lessons.md",20008,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Freferences\u002Ffield-lessons.md",{"path":55,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":56,"sourceHtmlUrl":57},"references\u002Fstacks.md",8255,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Freferences\u002Fstacks.md",{"path":59,"resourceType":46,"resourceTypeDesc":47,"sizeBytes":60,"sourceHtmlUrl":61},"references\u002Ftools-by-os.md",3708,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Freferences\u002Ftools-by-os.md",{"path":63,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":66,"sourceHtmlUrl":67},"scripts\u002Fcall-counts.mjs","SCRIPT","脚本",4363,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Fscripts\u002Fcall-counts.mjs",{"path":69,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":70,"sourceHtmlUrl":71},"scripts\u002Fdoctor.ps1",3261,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Fscripts\u002Fdoctor.ps1",{"path":73,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":74,"sourceHtmlUrl":75},"scripts\u002Fdoctor.sh",6318,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Fscripts\u002Fdoctor.sh",{"path":77,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":78,"sourceHtmlUrl":79},"scripts\u002Finstr-count.sh",3841,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Fscripts\u002Finstr-count.sh",{"path":81,"resourceType":64,"resourceTypeDesc":65,"sizeBytes":82,"sourceHtmlUrl":83},"scripts\u002Fratchet.mjs",4947,"https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskill-library\u002Fpacks\u002Factive\u002Fprovenfast\u002Fscripts\u002Fratchet.mjs",[85,92,99,106,115,122],{"skillNo":86,"name":87,"nameZh":6,"description":88,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":89,"categories":90,"keywords":91,"publishedAt":19},"01M7AS6BAQQ2WQJYS3WBNJPB2G","x-content","Create, rewrite, critique, select formats for, discover opportunities for, and learn from X\u002FTwitter content and X Articles for a technical AI-native developer\u002Fbuilder account. Use when turning ideas, source posts, releases, benchmarks, results, conversations, authenticated For You or creator-watch opportunities, or project evidence into an Original, Quote, Thread, Reply, or Article; reviewing article titles\u002Foutlines\u002Fvisual briefs\u002Flaunch hooks; improving drafts; choosing additive contributions from live X context; or learning from own-account outcomes. Own content intelligence only; compose with agent-browser for live X state and Growth OS for discovery provenance, approvals, measurement, and publication.","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Fx-content\u002FSKILL.md",[],[],{"skillNo":93,"name":94,"nameZh":6,"description":95,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":96,"categories":97,"keywords":98,"publishedAt":19},"01M7AS66FXQR8FEQYW8G8RJB2N","writing-plans","Create detailed implementation plans for multi-step software work before editing code. Use when requirements or a specification must become concrete file-level tasks, interfaces, acceptance criteria, risks, rollout, or explicitly required validation. Default to no test creation, test modification, test execution, TDD, regression-test, or coverage work unless the user, authoritative specification, or mandatory repository policy explicitly requires testing.","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Fwriting-plans\u002FSKILL.md",[],[],{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":105,"publishedAt":19},"01M7AS5ZCJX21NF2RESA2QDWPP","systematic-debugging","Root-cause debugging for concrete technical failures including bugs, failing builds or tests, integration issues, performance regressions, and unexpected behavior. Use before proposing or implementing a repair when diagnosis is required. Reproduce the symptom, trace the responsible owner, maintain one leading causal hypothesis, and falsify it with the smallest direct evidence. Compose with Causal Coding for source mutation; testing is opt-in and requires independent authorization.","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Fsystematic-debugging\u002FSKILL.md",[],[],{"skillNo":107,"name":108,"nameZh":6,"description":109,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":110,"licenseFileUrl":111,"sourceHtmlUrl":112,"categories":113,"keywords":114,"publishedAt":19},"01M7AS548FQ63SAB9G0X81VPGJ","skill-creator","Guide for creating and updating high-quality skills by translating workflows, conventions, and reusable processes into well-structured skills. Includes context, use case examples and spec for skills. Use this skill whenever a user asks to create, update, edit, improve, package, or troubleshoot a skill, and also for conversational questions about skills in ChatGPT (e.g., \"What are skills?\", \"What can I use skills for?\", \"What are the best skill use cases for me?\", \"Where can I find my skills?\").","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Fskill-creator\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Fskill-creator\u002FSKILL.md",[],[],{"skillNo":116,"name":117,"nameZh":6,"description":118,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":119,"categories":120,"keywords":121,"publishedAt":19},"01M7AS4XD121Q85Y06EXRGYS4F","reflexion","Self-refinement, multi-perspective critique, verification, and durable lesson curation adapted from NeoLabHQ Reflexion. Use when the user asks to reflect, self-review, critique, double-check, verify and improve prior work, run a rigorous review, memorize lessons, or says \"then reflect\" after a coding, analysis, or writing task. Supports repository-aware evidence gathering and works without subagents or Claude hooks.","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Freflexion\u002FSKILL.md",[],[],{"skillNo":123,"name":124,"nameZh":6,"description":125,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":126,"categories":127,"keywords":128,"publishedAt":19},"01M7AS4RN5TYMA4P6SK6K7NVSR","ponytail","Enforce Ponytail's lazy-senior-developer approach for coding, fixing, refactoring, design, dependency choices, and explicit Ponytail modes such as review, audit, debt, gain, and help. Prefer YAGNI, existing code, standard library, native platform features, existing dependencies, low reader load, and the smallest correct diff. For source mutation, keep Causal Coding authoritative for scope, testing authorization, verification cadence, and stopping. On connected WSL\u002FLinux targets, compose with MCP Harness Router and use `wsl-web-harness` for authoritative repository work.","https:\u002F\u002Fgithub.com\u002Fham-zax\u002Fwebharness\u002Fblob\u002Fmain\u002Fskills\u002Fponytail\u002FSKILL.md",[],[]]