Performance at scale
Skill Fergius-Engineering/instincts/skills/performance-at-scale
Working-instinct skills for Claude Code: verify claims against the source, log for the bug you can't reproduce, write like a human, test so the test bites. A reflex layer on top of superpowers.
npx -y skills add Fergius-Engineering/instincts --skill performance-at-scaleAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Use when writing code that runs per item, per frame, or per event, or building a cache or lookup over a collection that can grow large.
SKILL.md
2.0 KB, as published. Nobody here has run it
The rule
Hot-path code meets your data at production scale, not at the handful of rows in your test fixture. A linear scan that's instant on ten items freezes the UI on a hundred thousand. The cost is invisible in the test and brutal in the field. Design the hot path for the largest realistic input before you write it, not after a user reports a freeze.
Fires when
Writing code that runs per item, per frame, or per event. Building a cache or a lookup. Iterating a collection that could grow large. Rebuilding a whole list when one entry changed.
How to apply
Before writing data-path code, ask "does this hold at the largest realistic input?"
Use O(1) lookups with an early exit — a map keyed by the thing you're asking about, so 99% of queries return immediately. Prefer incremental point updates (remove one, add one) over rebuilding the whole structure. Keep allocations and copies out of tight loops. Verbose logging in a hot loop is fine, but only after the early exit, never before it.
If the answer is "no, it won't scale", redesign before you write it, not after.
Worked example
A handler runs once per tile and scans a flat list of issues linearly to find the ones that match. With a dozen issues in the test, it's instant. In a real project the list holds four thousand issues, and every tile now costs a one-to-two second freeze. Keyed into a map by tile, each query early-exits in O(1) and the freeze is gone. The scan looked fine because the test never had enough data to make it hurt.
Red flags
| Thought | Reality |
|---|---|
| "It's fast enough" | Fast on the fixture, frozen at scale. |
| "I'll rebuild the whole list, it's simpler" | Simpler to write, O(N) to run every time. |
| "Just loop and find it" | A linear scan on a hot path is a freeze waiting for data. |