Performance Tuning

Performance Tuning

Overview

Blind optimization is the root of wasted effort. Measure, pinpoint the bottleneck, fix that specific thing.

Core principle: No optimization without measurement. No measurement without a demonstrated performance problem.

No exceptions. No workarounds. No shortcuts.

The Prime Directive

NO OPTIMIZATION WITHOUT A MEASUREMENT PROVING THE PROBLEM

If you have not profiled it, you are not qualified to optimize it. Intuitions about performance are reliably wrong.

When to Use

digraph perf_gate {
    problem [label="Is there a\nmeasurable\nperformance deficit?", shape=diamond];
    measure [label="MEASURE\nProfile and locate\nthe bottleneck", shape=box, style=filled, fillcolor="#ccffcc"];
    halt [label="HALT\nDo not optimize", shape=box, style=filled, fillcolor="#ffcccc"];
    found [label="Bottleneck\npinpointed?", shape=diamond];
    fix [label="FIX\nthat specific thing", shape=box, style=filled, fillcolor="#ccccff"];
    dig [label="Investigate further\nor accept current\nperformance", shape=box];

    problem -> measure [label="yes"];
    problem -> halt [label="no"];
    measure -> found;
    found -> fix [label="yes"];
    found -> dig [label="no"];
    fix -> measure [label="re-measure"];
}

Engage when:

• Users report perceptible slowness
• Telemetry shows regression (response time, page load, throughput)
• Performance budgets are breached (bundle size, Core Web Vitals)
• Database queries exceed 100ms for routine operations
• API responses exceed 500ms for typical requests

Do not engage when:

• "It might be slow someday" (measure when it actually is)
• "Best practice recommends optimizing X" (is X actually slow?)
• Current performance satisfies current requirements
• The feature does not yet work correctly (correctness first)

The Entry Protocol

BEFORE any optimization effort:

1. MEASURE: What is the current performance? (Numbers, not hunches)
2. TARGET: What performance level is required? (Specific threshold)
3. PINPOINT: Where is the bottleneck? (Profiler data, not speculation)
4. FIX: Address that specific bottleneck
5. VERIFY: Did the measurement improve? By how much?

Omit any step = premature optimization

The Methodology

Phase 1: Establish a Baseline

You must have numbers before changing anything.

| Dimension | How to Measure | |---|---| | Page load latency | Lighthouse, WebPageTest, browser DevTools Performance panel | | API response time | Server logs, APM instrumentation, time curl | | Query execution time | EXPLAIN ANALYZE, slow query log, ORM query logging | | Bundle weight | webpack-bundle-analyzer, source-map-explorer | | Memory consumption | Heap snapshots, process.memoryUsage() | | CPU utilization | Flame charts via profiler, perf, py-spy |

Record the baseline. You need it to prove the optimization was effective.

Phase 2: Locate the Bottleneck

The bottleneck is almost never where you expect it.

Profile -> identify the function/query/resource consuming the most time
                                    |
                    That is your optimization target
                                    |
                    Everything else is a distraction

Check these locations in order (most common first):

1. Database queries -- N+1 patterns, absent indexes, full table scans
2. Network calls -- Sequential when parallelizable, no caching layer
3. Serialization -- Oversized payloads, unnecessary nested data
4. Computation -- Suboptimal algorithms, redundant processing
5. I/O operations -- File system access, disk reads, external API latency

Phase 3: Resolve the Bottleneck

Fix only what the profiler revealed. Change one variable at a time.

Database Tuning

| Symptom | Remedy | |---|---| | N+1 queries | Eager loading / JOIN / batched query | | Missing index | Add index on columns in WHERE/JOIN/ORDER BY clauses | | Full table scan | Add appropriate index; constrain result set | | Oversized result sets | Cursor-based pagination for large datasets | | Expensive aggregations | Materialized views or pre-computed summaries | | Lock contention | Tighten transaction scope; introduce read replicas |

-- BEFORE: Diagnose the problem
EXPLAIN ANALYZE SELECT * FROM transactions WHERE account_id = 789;

-- Look for: Seq Scan (missing index), high cost, slow execution
-- AFTER: Add index, re-run EXPLAIN ANALYZE, compare numbers

Frontend Tuning (Core Web Vitals)

| Metric | Threshold | Typical Remedies | |---|---|---| | LCP (Largest Contentful Paint) | Pinpoint bottleneck -> Fix that one thing -> Confirm improvement

Everything else is speculation. Speculation about performance is always wrong.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [NoobyGains](https://github.com/NoobyGains)
- **Source:** [NoobyGains/godmode](https://github.com/NoobyGains/godmode)
- **License:** MIT

Install and usage instructions live in the source repository linked above.