arbazkhan971/perf

Activate When

• /godmode:perf, "profile this", "find bottleneck"
• "memory leak", "race condition", "deadlock"
• "benchmark", "flame graph", "why is this slow"

Workflow

1. Profiling Strategy

# Node.js CPU profile
node --cpu-prof --cpu-prof-dir=./profiles app.js
# Go CPU profile
go tool pprof http://localhost:6060/debug/pprof/profile
# Python memory
python -c "import tracemalloc; tracemalloc.start()"

Target: <application/function>
Symptom: <slow response, high CPU, OOM, hang>
Language: <Node.js|Python|Go|Rust|Java>

2. CPU Profiling & Flame Graphs

For each hotspot found:

Function: <name> at <file>:<line>
CPU share: <N>% of total
Root cause: <why slow>
Remediation: <optimized code>
Expected improvement: <N>% reduction

IF hotspot >10% CPU: must address. IF hotspot <5% CPU: diminishing returns.

3. Memory Leak Detection

Tools: Node.js (--heap-prof), Python (tracemalloc), Go (pprof), Rust (DHAT), Java (JFR+JMC).

Pattern: baseline -> load -> analyze growth.

• Constant: OK
• Linear: leak
• Stepped: periodic leak

For each finding:

Type: LEAK | EXCESSIVE ALLOCATION | UNBOUNDED CACHE
Source: <file>:<line>
Growth rate: <MB per hour/request>
Retention chain: <root -> ... -> leaked object>

IF growth is linear under load: confirmed leak. IF cache grows without bound: add max size + eviction.

4. Concurrency Bug Detection

# Go race detector
go test -race ./...
# C/C++ thread sanitizer
gcc -fsanitize=thread -o app app.c && ./app

Common patterns: counter without atomic, lazy init without sync, collection modified during iteration, read-modify-write without transaction.

For each finding:

Type: RACE | DEADLOCK | LIVELOCK | STARVATION
Severity: CRITICAL | HIGH | MEDIUM
Code path: <file>:<line>
Reproducibility: always | under load | intermittent

Deadlock prevention: consistent lock ordering, try-lock with timeout, channels over shared memory.

5. Benchmarking

Protocol:
1. Dedicated hardware, disable frequency scaling
2. Warm-up iterations + measurement iterations
3. Report: mean, median, p95, p99, stddev, 95% CI
4. CV > 10% = unstable environment
5. Comparison: interleaved runs, Welch's t-test,
   p < 0.05 = statistically significant

IF benchmark variance >10%: fix environment first. NEVER benchmark on shared CI runners for final results. NEVER skip warm-up for JIT languages (Node, Java).

6. Report

CPU: top 3 hotspots with % and file:line
Memory: leaks found, growth rate, peak RSS
Concurrency: races, deadlock risks, contention
Benchmarks: values with 95% CI
Priority fixes: ordered by impact

Hard Rules

1. NEVER optimize without profiling first.
2. NEVER benchmark without confidence intervals.
3. NEVER benchmark on noisy/shared systems.
4. NEVER skip warm-up iterations (JIT languages).
5. NEVER profile debug builds (use release/prod).
6. ALWAYS measure before and after optimization.
7. ALWAYS report p95/p99, not just mean.

TSV Logging

Append .godmode/perf-results.tsv:

timestamp	module	finding_type	location	severity	metric_before	metric_after	status

Keep/Discard

KEEP if: improvement is statistically significant
  AND no regression AND tests pass.
DISCARD if: no significant improvement OR regression.
Never keep optimization without measured evidence.

Stop Conditions

STOP when FIRST of:
  - All hotspots >10% CPU addressed
  - Memory stable under sustained load
  - Zero races detected by sanitizer
  - 3 consecutive fixes < 5% improvement

Autonomous Operation

On failure: git reset --hard HEAD~1. Never pause.

<!-- tier-3 -->

Error Recovery

| Failure | Action | |--|--| | No clear hotspot | Check sampling rate, profile under load | | Optimization regresses | Measure all metrics, revert if needed | | Noisy benchmarks | Pin CPU, disable turbo, dedicated HW |