Profiles a running system to find real performance bottlenecks, establishes baseline measurements, applies targeted optimizations (query tuning, cache strategy, bundle reduction, async patterns), and validates improvement with before/after benchmarks. Produces PERF.md with evidence-backed findings and applied changes.
Profiles a running system to find real performance bottlenecks, establishes baseline measurements, applies targeted optimizations (query tuning, cache strategy, bundle reduction, async patterns), and validates improvement with before/after benchmarks. Produces PERF.md with evidence-backed findings and applied changes.
when_to_use
Use when there is a proven performance problem — slow endpoint, high memory, large bundle, degraded throughput — measured with real data. Invoke after go-crane (metrics show the problem) or after go-eagle (load tests reveal bottlenecks). Never invoke speculatively.
go-ant — Performance Profiling & Optimization
go-ant carries weight far beyond its size. It does not optimize speculatively — it profiles first, proves the problem, then removes exactly what is slow.
Quick start
Prerequisite: a measured performance problem (p95 > SLO, bundle > threshold, query > N ms)
User: "The /orders endpoint is timing out under load."
→ invoke go-ant
→ establish baseline → profile → identify bottleneck → apply fix → benchmark → PERF.md
Workflow
1. Establish baseline
Before touching any code, record current performance:
Identify the symptom: which endpoint, query, page, or operation is slow?
Record the baseline metric: p50, p95, p99 latency — or bundle size, memory, CPU, throughput — as appropriate
Identify the SLO or threshold being violated (if none exists, define one before proceeding)
Confirm the problem is reproducible in a stable environment (not a one-off spike)
Write findings to PERF.md under ## Baseline. Do not proceed without a numeric baseline. "It feels slow" is not a baseline.
2. Profile — find the bottleneck
Use the appropriate profiler for the stack. Do not guess:
Backend (Node.js):clinic.js, 0x, node --prof, or autocannon for load profiling
Backend (Go):pprof CPU and heap profiles, go test -bench, go tool traceBackend (Python):cProfile, py-spy, line_profilerDatabase:EXPLAIN ANALYZE (Postgres), SHOW PROFILE (MySQL), slow query log
Frontend — runtime: Chrome DevTools Performance tab, React Profiler, Lighthouse
Frontend — bundle:webpack-bundle-analyzer, vite-plugin-visualizer, source-map-explorerFrontend — network: Lighthouse, WebPageTest, Core Web Vitals
Run the profiler. Capture output as a file or screenshot.
Identify the top 3 consumers of time, memory, or bytes
Confirm the bottleneck is in application code — not in infra, network, or load generator noise
Record profiler findings in PERF.md under ## Profiler Output. Attach or link the profile file.
3. Diagnose the root cause
For each bottleneck found, determine why it is slow:
N+1 query: loop executing one query per record — fix with JOIN or batch load
Missing index: sequential scan on large table — fix with targeted index
Synchronous I/O in hot path: blocking call where async would work — fix with async/await or queue
Redundant computation: same value computed repeatedly — fix with memoization or cache
Over-fetching: returning more data than the client uses — fix with field selection or pagination
Large bundle: importing full library when only one function is used — fix with tree shaking or dynamic import
Layout thrash: DOM reads/writes interleaved — fix with batched DOM updates
Memory leak: objects retained past their lifetime — fix with cleanup or WeakRef
Write one sentence per bottleneck: "X is slow because Y."
Confirm the fix addresses the root cause, not the symptom
Record diagnoses in PERF.md under ## Root Cause.
4. Apply the fix
Implement the smallest change that resolves the bottleneck:
One fix per bottleneck. Do not bundle unrelated changes.
Do not refactor surrounding code. Performance fix only.
Do not add caching as a first resort — fix the underlying inefficiency first. Cache only when the computation is provably expensive and idempotent.
If the fix changes a database query, run EXPLAIN ANALYZE before and after to confirm the plan changed.
If the fix changes a bundle, verify tree shaking or code splitting took effect with the bundle analyzer.
5. Benchmark — validate the improvement
Re-run the same measurement used in Step 1:
Record the new p50/p95/p99 (or size, memory, throughput) under identical conditions
Confirm the metric now meets or beats the SLO defined in Step 1
Confirm no regression in correctness (run existing test suite)
If the improvement is less than 20% over baseline, question whether the fix addressed the actual bottleneck
Write results to PERF.md under ## Benchmark Results as a before/after table:
Metric
Before
After
Delta
p95 latency
1200ms
320ms
-73%
6. Produce PERF.md
Final document must include:
## Baseline — the original measured problem with numeric value
## Profiler Output — raw profiler data or link to file
## Root Cause — one-sentence diagnosis per bottleneck
## Changes Applied — list of code changes made, with rationale
## Benchmark Results — before/after table
## Remaining Work — bottlenecks identified but not yet fixed, with estimated impact
Rules
Do not invoke go-ant without a numeric baseline. Speculative optimization is prohibited.
Do not apply more than one fix at a time. Measure after each change, or you cannot attribute the improvement.
Do not cache before fixing the underlying inefficiency. Caching a broken implementation hides the problem.
Do not refactor surrounding code during a performance fix. go-ant does one thing: remove the bottleneck.
If the profiler shows the bottleneck is in infra or a third-party service, stop. Document the finding in PERF.md and escalate — go-ant does not fix what it does not own.
Output
PERF.md — baseline, profiler output, root cause diagnoses, changes applied, benchmark results, remaining work
Before/after benchmark table confirming SLO is met
Position in the pack
... → go-crane → [go-ant] → go-owl
↑
also invokable after go-eagle (load tests reveal bottleneck)
or standalone when a specific slow operation is already known
go-crane provides the metrics that surface the problem. go-ant fixes it. go-owl documents the changes in runbooks and changelogs. go-bear should review any caching or async patterns introduced by go-ant for security implications.
