perf-skills 1.0.3 → 2.0.0

package/skills/perf/references/topics/protocol-testing.md

@@ -1,22 +1,22 @@
 # Protocol-Specific Performance Testing
 
-Covers gRPC, GraphQL, WebSocket/SSE, and message queue (Kafka, RabbitMQ, SQS) load testing — protocols with unique challenges beyond standard HTTP/REST.
+Covers gRPC, GraphQL, WebSocket/SSE, and message queue (Kafka, RabbitMQ, SQS) load testing - protocols with unique challenges beyond standard HTTP/REST.
 
 ---
 
 ## gRPC Performance Testing
 
-gRPC uses HTTP/2, Protocol Buffers, and persistent connections — fundamentally different from REST at the wire level.
+gRPC uses HTTP/2, Protocol Buffers, and persistent connections - fundamentally different from REST at the wire level.
 
 ### Key Challenges
 
 | Challenge | Why It Matters |
 |---|---|
 | **Protobuf compilation** | Tests require compiled `.proto` definitions; can't just send raw JSON |
-| **Connection multiplexing** | HTTP/2 multiplexes streams over a single connection — fewer connections needed but different bottleneck profile |
+| **Connection multiplexing** | HTTP/2 multiplexes streams over a single connection - fewer connections needed but different bottleneck profile |
 | **Streaming** | Unary, server-streaming, client-streaming, and bidirectional-streaming each need different test strategies |
 | **Metadata vs headers** | gRPC metadata is the equivalent of HTTP headers; auth tokens go here |
-| **Error codes** | gRPC uses its own status codes (OK, UNAVAILABLE, DEADLINE_EXCEEDED) — not HTTP status codes |
+| **Error codes** | gRPC uses its own status codes (OK, UNAVAILABLE, DEADLINE_EXCEEDED) - not HTTP status codes |
 
 ### Tool Support
 
@@ -58,14 +58,14 @@ export default function () {
 - **Connection reuse**: Keep connections open across iterations; don't connect/close per request.
 - **Streaming throughput**: For server-streaming RPCs, measure messages-per-second, not just request latency.
 - **Deadline propagation**: Set gRPC deadlines in tests to match production timeouts.
-- **Load balancer awareness**: gRPC over HTTP/2 with persistent connections can cause uneven load across backends — test with client-side load balancing or L7 proxy.
-- **Protobuf payload size**: Binary encoding is smaller than JSON — adjust throughput expectations accordingly.
+- **Load balancer awareness**: gRPC over HTTP/2 with persistent connections can cause uneven load across backends - test with client-side load balancing or L7 proxy.
+- **Protobuf payload size**: Binary encoding is smaller than JSON - adjust throughput expectations accordingly.
 
 ---
 
 ## GraphQL Performance Testing
 
-GraphQL introduces query complexity as a variable — the same endpoint can serve trivially cheap or devastatingly expensive requests.
+GraphQL introduces query complexity as a variable - the same endpoint can serve trivially cheap or devastatingly expensive requests.
 
 ### Key Challenges
 
@@ -79,7 +79,7 @@ GraphQL introduces query complexity as a variable — the same endpoint can serv
 
 ### Testing Strategy
 
-1. **Catalog production queries**: Extract real queries from logs or APM traces — don't invent synthetic queries.
+1. **Catalog production queries**: Extract real queries from logs or APM traces - don't invent synthetic queries.
 2. **Categorize by cost**: Light (single field), medium (nested 2 levels), heavy (deep joins, lists).
 3. **Build a realistic query mix**: Weight tests by actual production query distribution.
 4. **Test with and without caching**: GraphQL caching (DataLoader, CDN) dramatically changes performance profiles.
@@ -136,7 +136,7 @@ Persistent connections have fundamentally different scaling characteristics from
 
 | Challenge | Why It Matters |
 |---|---|
-| **Connection count** | Each VU holds an open connection — tests memory/fd limits, not just CPU |
+| **Connection count** | Each VU holds an open connection - tests memory/fd limits, not just CPU |
 | **Message throughput** | Measure messages/sec independently from connection count |
 | **Backpressure** | What happens when the server can't send fast enough? |
 | **Reconnection behavior** | Dropped connections should auto-reconnect; test the reconnect storm |
@@ -194,7 +194,7 @@ export default function () {
 
 ### WebSocket Testing Strategy
 
-1. **Connection ramp**: Gradually open connections — don't blast 10k connections at once.
+1. **Connection ramp**: Gradually open connections - don't blast 10k connections at once.
 2. **Separate connection test from message test**: First, find max stable connections; then test message throughput at a stable connection count.
 3. **Measure server-side**: File descriptor count, memory per connection, event loop lag.
 4. **Test reconnection storms**: Kill server, observe client reconnection behavior and server recovery.
@@ -211,7 +211,7 @@ Testing Kafka, RabbitMQ, SQS, and similar systems requires measuring producer th
 |---|---|
 | **Producer throughput** | Messages/sec the system can ingest |
 | **Consumer lag** | How far behind consumers fall under load |
-| **End-to-end latency** | Time from produce to consume — the real user-facing metric |
+| **End-to-end latency** | Time from produce to consume - the real user-facing metric |
 | **Partition scaling** | Kafka throughput scales with partitions; test with realistic partition counts |
 | **Message ordering** | Under load, verify ordering guarantees still hold |
 | **Dead letter queues** | Verify failed messages route correctly under pressure |
@@ -256,10 +256,10 @@ export function teardown() {
 ### Message Queue Testing Strategy
 
 1. **Test producers and consumers separately first**, then together.
-2. **Measure consumer lag over time** — a growing lag under steady load indicates a bottleneck.
-3. **Test with realistic message sizes** — a 100-byte message vs a 1MB payload have very different throughput ceilings.
-4. **Verify idempotency** — under load with retries, duplicate messages should not corrupt state.
-5. **Test partition rebalancing** — add/remove consumers during a test to verify rebalance behavior.
+2. **Measure consumer lag over time** - a growing lag under steady load indicates a bottleneck.
+3. **Test with realistic message sizes** - a 100-byte message vs a 1MB payload have very different throughput ceilings.
+4. **Verify idempotency** - under load with retries, duplicate messages should not corrupt state.
+5. **Test partition rebalancing** - add/remove consumers during a test to verify rebalance behavior.
 
 ---
 

package/skills/perf/references/topics/results-analysis.md

@@ -1,6 +1,6 @@
 # Results Analysis
 
-Interpreting performance test results is a skill in itself. Raw numbers are meaningless without context — this reference covers how to read, analyze, and act on performance data.
+Interpreting performance test results is a skill in itself. Raw numbers are meaningless without context - this reference covers how to read, analyze, and act on performance data.
 
 ---
 
@@ -9,12 +9,12 @@ Interpreting performance test results is a skill in itself. Raw numbers are mean
 | Metric | Description | Target |
 |---|---|---|
 | **Throughput** | Requests per second (RPS / TPS) | ≥ defined baseline |
-| **Response Time (p50)** | Median — half of requests faster than this | Per SLA |
-| **Response Time (p95)** | 95% of requests faster than this — main SLA metric | Per SLA |
-| **Response Time (p99)** | Tail latency — reveals worst-case behavior | Per SLA |
+| **Response Time (p50)** | Median - half of requests faster than this | Per SLA |
+| **Response Time (p95)** | 95% of requests faster than this - main SLA metric | Per SLA |
+| **Response Time (p99)** | Tail latency - reveals worst-case behavior | Per SLA |
 | **Error Rate** | % of failed requests | < 1% (or as defined) |
 | **Active VUs / Concurrency** | Number of simulated users at any point | Matches load profile |
-| **Network I/O** | Bytes/sec in and out — detects bandwidth bottlenecks | Headroom vs NIC capacity |
+| **Network I/O** | Bytes/sec in and out - detects bandwidth bottlenecks | Headroom vs NIC capacity |
 
 ---
 
@@ -47,9 +47,9 @@ Example: 100 requests
 | Column | Meaning |
 |---|---|
 | # Samples | Total requests sent |
-| Average | Mean response time (ms) — use sparingly |
+| Average | Mean response time (ms) - use sparingly |
 | Min / Max | Absolute floor and ceiling |
-| Std. Dev. | Variance — high deviation = inconsistent behavior |
+| Std. Dev. | Variance - high deviation = inconsistent behavior |
 | Error % | Percentage of failed requests |
 | Throughput | Requests/second |
 | KB/sec | Network throughput |
@@ -57,11 +57,11 @@ Example: 100 requests
 
 ### HTML Dashboard
 Generated with `-e -o results/dashboard` flag. Key graphs:
-- **Response Time Over Time** — spot degradation trends
-- **Transactions Per Second** — confirm throughput matches expectation
-- **Response Time Percentiles** — see distribution
-- **Active Threads Over Time** — correlate with response time
-- **Errors Over Time** — when and what errors spike
+- **Response Time Over Time** - spot degradation trends
+- **Transactions Per Second** - confirm throughput matches expectation
+- **Response Time Percentiles** - see distribution
+- **Active Threads Over Time** - correlate with response time
+- **Errors Over Time** - when and what errors spike
 
 ### JTL Analysis (programmatic)
 ```python
@@ -191,7 +191,7 @@ Sudden jump at a load threshold = system has hit a constraint (thread limit, DB
 
 ## Comparing Runs (Trend Analysis)
 
-Always compare the current run against a baseline — never evaluate a run in isolation.
+Always compare the current run against a baseline - never evaluate a run in isolation.
 
 | Metric | Run 1 (Baseline) | Run 2 | Delta | Status |
 |---|---|---|---|---|

package/skills/perf/references/topics/script-generation.md

@@ -1,6 +1,6 @@
 # Script Generation & Best Practices
 
-This reference covers how to write robust, realistic, and maintainable performance test scripts — regardless of tool. Apply these principles to JMeter, k6, Gatling, Locust, or any other tool.
+This reference covers how to write robust, realistic, and maintainable performance test scripts - regardless of tool. Apply these principles to JMeter, k6, Gatling, Locust, or any other tool.
 
 ---
 
@@ -55,7 +55,7 @@ Correlation is extracting a dynamic value from a response and using it in a subs
 ### Correlation debugging approach
 1. Run the script with 1 VU.
 2. Look for HTTP 4xx errors (especially 403 Forbidden, 422 Unprocessable Entity).
-3. Check the request body/headers — is a token missing or stale?
+3. Check the request body/headers - is a token missing or stale?
 4. Use the tool's debug output or proxy (Fiddler, Charles) to inspect live traffic.
 5. Identify where the value appears in a *previous* response.
 6. Add an extractor at that response, reference the variable in the failing request.
@@ -64,14 +64,14 @@ Correlation is extracting a dynamic value from a response and using it in a subs
 
 ## Assertions (Why They're Non-Negotiable)
 
-Without assertions, your test might generate 1000 RPS of 404 responses or empty bodies — and your metrics will look "fine."
+Without assertions, your test might generate 1000 RPS of 404 responses or empty bodies - and your metrics will look "fine."
 
 ### What to assert
-- **Status code** — the obvious one; but also check for 200s that contain error bodies.
-- **Response body** — key field exists and has expected value.
-- **Response time** — flag individual responses over SLA as failures.
-- **Response size** — detect truncated or empty bodies.
-- **Content-Type header** — ensure you got JSON, not an HTML error page.
+- **Status code** - the obvious one; but also check for 200s that contain error bodies.
+- **Response body** - key field exists and has expected value.
+- **Response time** - flag individual responses over SLA as failures.
+- **Response size** - detect truncated or empty bodies.
+- **Content-Type header** - ensure you got JSON, not an HTML error page.
 
 ### Assertion layering
 
@@ -141,7 +141,7 @@ Most tools handle cookies automatically. Verify the Cookie Manager is enabled.
 1. Authenticate in `setup()` or `on_start()`.
 2. Store the token in session variables.
 3. Add as Authorization header to subsequent requests.
-4. Handle token expiry — check for 401 responses and re-authenticate.
+4. Handle token expiry - check for 401 responses and re-authenticate.
 
 ```javascript
 // k6: handle token refresh

package/skills/perf/references/topics/test-data.md

@@ -6,10 +6,10 @@ Test data is a first-class concern in performance testing. Bad data causes false
 
 ## Why Test Data Matters
 
-- **Authentication tokens** expire — hardcoded tokens fail within minutes.
+- **Authentication tokens** expire - hardcoded tokens fail within minutes.
 - **Unique constraints** (email, username, order number) cause failures at concurrency > 1.
 - **State-dependent flows** (checkout, approval) require data in the right state before the test.
-- **Cache effects** — if 1000 VUs all hit the same product ID, cache hit rates are unrealistically high; spread data across IDs.
+- **Cache effects** - if 1000 VUs all hit the same product ID, cache hit rates are unrealistically high; spread data across IDs.
 
 ---
 
@@ -17,7 +17,7 @@ Test data is a first-class concern in performance testing. Bad data causes false
 
 | Test Type | Data Strategy |
 |---|---|
-| Smoke (1 VU) | Minimal — single known-good user/record |
+| Smoke (1 VU) | Minimal - single known-good user/record |
 | Load (realistic VUs) | Pool of pre-created users/records matching production volume |
 | Stress (pushing limits) | Large pool; no uniqueness conflicts |
 | Soak (hours) | Rotating/recyclable data; handle state cleanup |
@@ -78,7 +78,7 @@ TO '/tmp/users.csv' CSV HEADER;
 Best for: data that must be in a specific state per VU (unique cart, session, transaction).
 
 ```javascript
-// k6 setup() — run before VUs start
+// k6 setup() - run before VUs start
 export function setup() {
   const orders = [];
   for (let i = 0; i < 200; i++) {
@@ -103,7 +103,7 @@ def on_start(self):
 
 ### Strategy 4: Faker / Synthetic Data Generation
 
-Best for: registration flows, profile creation, form submission — where each VU needs unique PII-like data.
+Best for: registration flows, profile creation, form submission - where each VU needs unique PII-like data.
 
 ```python
 # Python (Locust or data generation script)
@@ -169,7 +169,7 @@ Each VU/iteration picks the next row. Ensures even distribution.
 Better for cache-busting tests where you want realistic cache miss rates.
 
 ### Unique-Per-VU
-Each VU gets a dedicated row — critical for state-dependent flows (user owns specific order). Use VU index (`__VU` in k6, `${__threadNum}` in JMeter) to deterministically select a row.
+Each VU gets a dedicated row - critical for state-dependent flows (user owns specific order). Use VU index (`__VU` in k6, `${__threadNum}` in JMeter) to deterministically select a row.
 
 ```javascript
 // k6: VU-indexed data

package/skills/perf/references/topics/test-execution.md

@@ -1,6 +1,6 @@
 # Test Execution
 
-Covers how to run performance tests reliably — locally, in CI/CD pipelines, distributed across injectors, and in the cloud.
+Covers how to run performance tests reliably - locally, in CI/CD pipelines, distributed across injectors, and in the cloud.
 
 ---
 
@@ -19,7 +19,7 @@ Covers how to run performance tests reliably — locally, in CI/CD pipelines, di
 
 - Always use **non-GUI / headless mode** for actual load runs (GUI mode adds overhead).
 - Run scripts from the same network segment as the system under test when possible.
-- Monitor injector machine resources during the test — if CPU/memory of the injector saturates, results are invalid.
+- Monitor injector machine resources during the test - if CPU/memory of the injector saturates, results are invalid.
 - Set JVM heap appropriately for JMeter: `JVM_ARGS="-Xms2g -Xmx4g" jmeter -n -t test.jmx`
 
 ---
@@ -47,7 +47,7 @@ remote_hosts=injector-1:1099,injector-2:1099,injector-3:1099
 jmeter -n -t test.jmx -r -l results.jtl -Jthreads=300 -Jduration=600
 ```
 
-**Ports to open:** 1099 (RMI control), 50000+ (dynamic data ports) — firewall rules critical.
+**Ports to open:** 1099 (RMI control), 50000+ (dynamic data ports) - firewall rules critical.
 
 **Scaling:** Each injector can typically handle 300–500 VUs for HTTP at moderate response times. For 10k VUs, plan 20–30 injectors.
 
@@ -136,7 +136,7 @@ Code PR  →  Build  →  Unit/Integration Tests  →  [Performance Gate]  →
                                                          └─ PASS → Deploy / FAIL → Block
 ```
 
-### GitHub Actions — k6
+### GitHub Actions - k6
 
 ```yaml
 name: Performance Gate
@@ -183,7 +183,7 @@ jobs:
           # For additional reporting, parse results.json here
 ```
 
-### GitHub Actions — JMeter
+### GitHub Actions - JMeter
 
 ```yaml
       - name: Run JMeter Tests

package/skills/perf/references/topics/workload-design.md

@@ -1,6 +1,6 @@
 # Workload Design
 
-Workload design is the most impactful phase of performance testing. A poorly designed workload produces results that are irrelevant to production behavior — no matter how well-scripted the test is.
+Workload design is the most impactful phase of performance testing. A poorly designed workload produces results that are irrelevant to production behavior - no matter how well-scripted the test is.
 
 ---
 
@@ -153,7 +153,7 @@ Every test must have explicit, measurable SLA targets before execution. Negotiat
 | Max response time | < 5,000ms |
 
 **Why percentiles matter more than averages:**
-Average response time hides outliers. p95 tells you what 95% of users experience — averages can look fine while 10% of users timeout.
+Average response time hides outliers. p95 tells you what 95% of users experience - averages can look fine while 10% of users timeout.
 
 ---
 
@@ -185,7 +185,7 @@ Pacing is used when you want `N` iterations per hour per VU regardless of respon
 
 ## Ramp-Up Strategy
 
-Bad ramp-up causes a "thundering herd" — thousands of VUs hitting the server simultaneously, warming up connection pools, JVM, and caches all at once. This is unrealistic and produces misleading results.
+Bad ramp-up causes a "thundering herd" - thousands of VUs hitting the server simultaneously, warming up connection pools, JVM, and caches all at once. This is unrealistic and produces misleading results.
 
 **Good ramp-up:**
 - Rule of thumb: Ramp to 100% over at least 5–10 minutes for large tests.