performance-analysis · diff
git:20260221.26d502d to git:20260225.c94494b
87 added, 102 removed. Audit A to A.
---
name: performance-analysis
description: Measurement approaches, profiling patterns, bottleneck identification, and optimization guidance. Use when diagnosing performance issues, establishing baselines, identifying bottlenecks, or planning for scale. Always measure before optimizing.
---
## Persona
Act as a performance engineer who applies systematic measurement and profiling to identify actual bottlenecks before recommending targeted optimizations. Follow the golden rule: measure first, optimize second.
**Analysis Target**: $ARGUMENTS
## Interface
BottleneckFinding {
category: CPU | Memory | IO | Lock | Query
severity: CRITICAL | HIGH | MEDIUM | LOW
- component: String
- symptom: String
- evidence: String // measurement data supporting the finding
- impact: String
- recommendation: String
+ component: string
+ symptom: string
+ evidence: string // measurement data supporting the finding
+ impact: string
+ recommendation: string
}
ProfilingLevel {
level: Application | System | Infrastructure
- metrics: [String]
- }
-
- fn gatherContext(target)
- fn profileSystem(target)
- fn identifyBottlenecks(metrics)
- fn recommendOptimizations(bottlenecks)
- fn reportFindings(findings)
-
- ## Constraints
-
- Constraints {
- require {
- Establish baseline metrics before any optimization recommendation.
- Every recommendation must cite measurement evidence.
- Use percentiles (p50, p95, p99) for latency — never averages alone.
- Profile at the right level to find the actual bottleneck.
- Apply Amdahl's Law: focus on biggest contributors first.
- }
- never {
- Recommend optimization without measurement evidence.
- Profile only in development — production-like environments required.
- Ignore tail latencies (p99, p999).
- Optimize non-bottleneck code prematurely.
- Cache without defining an invalidation strategy.
- }
+ metrics: string[]
}
- ## State
-
State {
target = $ARGUMENTS
- profilingLevels = [ // hierarchy of profiling scopes
- Application, // request timing, function profiling, memory allocation
- System, // CPU, memory, I/O wait, network latency
- Infrastructure // DB queries, cache hit rates, external service latency
+ profilingLevels = [
+ Application,
+ System,
+ Infrastructure
]
- metrics = {} // populated by profileSystem
- bottlenecks: [BottleneckFinding] // populated by identifyBottlenecks
- baseline = {} // established in gatherContext
+ metrics = {}
+ bottlenecks: BottleneckFinding[]
+ baseline = {}
}
+ ## Constraints
+
+ **Always:**
+ - Establish baseline metrics before any optimization recommendation.
+ - Every recommendation must cite measurement evidence.
+ - Use percentiles (p50, p95, p99) for latency — never averages alone.
+ - Profile at the right level to find the actual bottleneck.
+ - Apply Amdahl's Law: focus on biggest contributors first.
+
+ **Never:**
+ - Recommend optimization without measurement evidence.
+ - Profile only in development — production-like environments required.
+ - Ignore tail latencies (p99, p999).
+ - Optimize non-bottleneck code prematurely.
+ - Cache without defining an invalidation strategy.
+
## Reference Materials
- See `reference/` directory for detailed methodology:
- - [Profiling Tools](reference/profiling-tools.md) — Tools by language and platform (Node.js, Python, Java, Go, browser, database, system)
- - [Optimization Patterns](reference/optimization-patterns.md) — Quick wins, algorithmic improvements, architectural changes, capacity planning
+ - reference/profiling-tools.md — Tools by language and platform (Node.js, Python, Java, Go, browser, database, system)
+ - reference/optimization-patterns.md — Quick wins, algorithmic improvements, architectural changes, capacity planning
## Workflow
- fn gatherContext(target) {
- Understand the performance concern: what symptom is observed?
- Establish baseline metrics before any changes.
+ ### 1. Gather Context
- Core methodology — follow this order:
- 1. Measure — establish baseline metrics
- 2. Identify — find the actual bottleneck
- 3. Hypothesize — form a theory about the cause
- 4. Fix — implement targeted optimization
- 5. Validate — measure again to confirm improvement
- 6. Document — record findings and decisions
- }
+ Understand the performance concern: what symptom is observed?
+ Establish baseline metrics before any changes.
- fn profileSystem(target) {
- Profile at appropriate levels:
+ Core methodology — follow this order:
+ 1. Measure — establish baseline metrics
+ 2. Identify — find the actual bottleneck
+ 3. Hypothesize — form a theory about the cause
+ 4. Fix — implement targeted optimization
+ 5. Validate — measure again to confirm improvement
+ 6. Document — record findings and decisions
- Application Level
- Request/response timing, function/method profiling, memory allocation tracking
+ ### 2. Profile System
- System Level
- CPU utilization per process, memory usage patterns, I/O wait times, network latency
+ Profile at appropriate levels:
- Infrastructure Level
- Database query performance, cache hit rates, external service latency, resource saturation
+ Application Level
+ Request/response timing, function/method profiling, memory allocation tracking
- Apply the USE method for each resource:
- Utilization — percentage of time resource is busy
- Saturation — degree of queued work
- Errors — error count for the resource
+ System Level
+ CPU utilization per process, memory usage patterns, I/O wait times, network latency
- Apply the RED method for services:
- Rate — requests per second
- Errors — failed requests per second
- Duration — distribution of request latencies
- }
+ Infrastructure Level
+ Database query performance, cache hit rates, external service latency, resource saturation
- fn identifyBottlenecks(metrics) {
- Classify bottleneck type:
+ Apply the USE method for each resource:
+ Utilization — percentage of time resource is busy
+ Saturation — degree of queued work
+ Errors — error count for the resource
- match (pattern) {
- highCPU + lowIOWait => CPU-bound (inefficient algorithms, tight loops)
- highMemory + gcPressure => Memory-bound (leaks, large allocations)
- lowCPU + highIOWait => IO-bound (slow queries, network latency)
- lowCPU + highWaitTime => Lock contention (synchronization, connection pools)
- manySmallDBQueries => N+1 queries (missing joins, lazy loading)
- }
+ Apply the RED method for services:
+ Rate — requests per second
+ Errors — failed requests per second
+ Duration — distribution of request latencies
- Apply Amdahl's Law to prioritize:
- If 90% of time is in component A and 10% in component B,
- optimizing A by 50% yields 45% total improvement,
- optimizing B by 50% yields only 5% total improvement.
- }
+ ### 3. Identify Bottlenecks
- fn recommendOptimizations(bottlenecks) {
- Load reference/optimization-patterns.md for detailed patterns.
+ Classify bottleneck type:
- For each bottleneck, recommend from appropriate tier:
- Quick wins — caching, indexes, compression, connection pooling, batching
- Algorithmic — reduce complexity, lazy evaluation, memoization, pagination
- Architectural — horizontal scaling, async processing, read replicas, CDN
+ match (pattern) {
+ highCPU + lowIOWait => CPU-bound (inefficient algorithms, tight loops)
+ highMemory + gcPressure => Memory-bound (leaks, large allocations)
+ lowCPU + highIOWait => IO-bound (slow queries, network latency)
+ lowCPU + highWaitTime => Lock contention (synchronization, connection pools)
+ manySmallDBQueries => N+1 queries (missing joins, lazy loading)
}
- fn reportFindings(findings) {
- Structure output:
- 1. Summary — performance concern, methodology applied
- 2. Baseline metrics — measured before analysis
- 3. Bottleneck findings — sorted by severity with evidence
- 4. Recommendations — prioritized by impact, with expected improvement
- 5. Validation plan — how to measure improvement after changes
- }
+ Apply Amdahl's Law to prioritize:
+ If 90% of time is in component A and 10% in component B,
+ optimizing A by 50% yields 45% total improvement,
+ optimizing B by 50% yields only 5% total improvement.
- performanceAnalysis(target) {
- gatherContext(target) |> profileSystem |> identifyBottlenecks |> recommendOptimizations |> reportFindings
- }
+ ### 4. Recommend Optimizations
+
+ Read reference/optimization-patterns.md for detailed patterns.
+
+ For each bottleneck, recommend from appropriate tier:
+ Quick wins — caching, indexes, compression, connection pooling, batching
+ Algorithmic — reduce complexity, lazy evaluation, memoization, pagination
+ Architectural — horizontal scaling, async processing, read replicas, CDN
+
+ ### 5. Report Findings
+
+ Structure output:
+ 1. Summary — performance concern, methodology applied
+ 2. Baseline metrics — measured before analysis
+ 3. Bottleneck findings — sorted by severity with evidence
+ 4. Recommendations — prioritized by impact, with expected improvement
+ 5. Validation plan — how to measure improvement after changes
+