Happier Profile And Optimize

Happier Profile and Optimize

Use this skill for any work whose success is a measured cost, not a behavior: slow open/foreground/navigation, jank, hangs, startup, memory, render churn, a query that got slow, or verifying somebody's speedup claim. It is the investigation method — reach for it once a cost exists.

It is deliberately not the list of things to watch for while writing code. Those must apply unprompted, at authoring time, long before anyone suspects a problem, so they live in package instructions that are read on every task: apps/ui/AGENTS.md → Performance and continuity owns the UI write-time invariants (referential stability, narrow subscriptions, component-type stability, high-frequency state placement, dependency-array identity, loop stop conditions, one perf change lands on all platforms). If you are about to restate one of those here, stop and strengthen it there instead.

The rules this skill operates under also live elsewhere and are not restated: root AGENTS.md → Product priorities (name the phase and metric, instrument must be able to see the cost, no ratio without both sides on the same workload and machine state, no blanket memoization) and Risk-weighted execution. Read those; do not re-derive them.

Route out, do not absorb:

• .agents/skills/happier-diagnose — the incident is a failure (error, hang-to-crash, broken session), not a cost. Diagnose first, then return here only if the outcome is a cost.
• .agents/skills/happier-testing — lanes, RED/GREEN, mutation proof, live gates. A perf fix with a behavior change is still test-first there.
• .agents/skills/happier-implement — the actual change, canonical-owner discovery, split-brain sweep.
• .agents/skills/verify-claims — before relying on any delegated or reported number.
• .agents/skills/attack-conclusion — before handing off a perf verdict.

1. Frame the cost before touching an instrument

State, in one line each: the phase (cold open, warm foreground, navigation, steady state, per-commit), the metric (blocked ms, count, bytes, dropped frames), the workload (session size, row count, account), and the user-visible symptom. A metric without a phase cannot be reproduced or compared.

Measure the moment that hurts. Some costs are steady-state, not open-time; some are per-commit rather than a resting loop. Profiling the wrong moment produces a real number about the wrong thing.

2. Pick the instrument that can see the cost

Get a total first — total blocked/elapsed time for the phase — then reconcile every instrument's attributed total against it, per the instrument-coverage rule in root AGENTS.md. What that rule costs when skipped, measured here: a React profiler reported ~1.4 s while the JS thread was blocked ~12 s; 88% of the cost was outside React, and a full round of work went into render churn that was not the bottleneck.

Route to the instrument by what it can observe:

Do not restate their contents; open the one you need.

Server and database work uses this same method — the instrument just changes. Read a plan for its shape, not its cost number: which index was chosen, which columns the Index Cond actually binds, and what residual predicate landed in Filter:. Run every engine that ships, because they disagree in ways that change the diagnosis: here the same attention query was a bare SCAN main.Session on SQLite but a Bitmap Index Scan on Postgres whose index condition bound only meaningfulActivityAt IS NOT NULL, leaving accountId in the Filter: — an account-wide scan wearing a bitmap. Isolate the cause with counterfactual query shapes, not by reading the query: dropping one OR arm at a time proved the intended index existed and was correct all along, and that a visibility OR alone was sufficient to destroy the seek. Costs on a small dev table are planner estimates, not production timings; the shape is the load-bearing part, and it must be engine-consistent before you act on it.

Memory work distinguishes allocation traffic from retention. Record cumulative allocations/GC separately from live heap, external/native memory, and process footprint. Compare repeated warmed workloads after the same idle/release window and, when the runtime permits it, a diagnostic full collection. Count retained domain records and inspect strong retaining paths before calling growth a leak. A weak-key cache is not proof of collectability when its values are opaque native handles: native code may strongly root the key. Use held-handle and dropped-handle controls across collections to establish that lifetime before changing application callbacks or retention policy. A heap snapshot, debugger, error log, or long Fast Refresh session can itself retain substantial memory; establish that measurement state before claiming application savings. Never add forced GC to product behavior as the fix. Record runtime reloads: a trace interrupted by Fast Refresh is not a continuous workload. For a bounded capture, use existing client development controls to pause auto-refresh, then restore them; preserve the loaded-source identity and respect managed-server ownership. Native-code dependency patches require a rebuilt development client; reconcile generated native projects through the existing build tooling and verify launch/component registration, since compile success and Fast Refresh cannot establish that the patched native path runs. A JavaScript-only dependency patch instead needs an app JavaScript reload and a probe of the loaded patched behavior; it does not itself require a native rebuild.

For unexplained growth after a controlled warmed repeat, the next investigation must identify surviving allocations and their lifetime owner, not merely repeat or widen navigation and collect another total. Disabled React profiling does not establish an empty developer-tool baseline: inspect buffered DevTools operations/history and use its existing connection/flush lifecycle as a diagnostic control before attributing that retention to the app. Object counts and shortest root paths are not dominator-retained sizes; account for weak-key/ephemeron semantics when interpreting a heap graph. For a native/external residual, compare app-specific allocation generations and allocating stacks, then inspect native ownership or memory graphs; RSS alone cannot distinguish live allocations, leaked ownership, allocator reserve, and mapped memory.

Locate in time, then in code. Block timing (e.g. a 16 ms drift sampler armed over the phase) tells you when the thread was stolen; a CPU profile with call paths tells you what stole it. Never fix something located only in time — a time window plus a plausible suspect is a hypothesis, not an attribution.