Skill: performance-guardian

Purpose

Add a performance verification gate to prevent regressions. This skill ensures that new code does not significantly degrade the performance of the application.

When to Use

• •After the Automated Testing gate passes.
• •For user stories that involve performance-sensitive code (e.g., database queries, rendering loops, API endpoints).

How It Works

Step 1: Define Benchmarks

In your CLAUDE.md, define the performance benchmarks:

## Performance Benchmarks

- **Command**: `npm run benchmark`
- **Baseline File**: `.ralph/performance.baseline.json`
- **Metrics**:
  - `api_response_time_p95`: 95th percentile API response time (ms)
  - `page_load_time`: Time to interactive (ms)
  - `memory_usage_peak`: Peak memory usage (MB)
- **Regression Threshold**: 10% (fail if any metric degrades by more than 10%)

Step 2: Establish Baseline (One-Time Setup)

Run the benchmark command and save the results as the baseline:

npm run benchmark --json > .ralph/performance.baseline.json

Step 3: Run Benchmarks After Code Changes

After the Automated Testing gate passes, run the benchmarks again:

npm run benchmark --json > .ralph/performance.current.json

Step 4: Compare Against Baseline

Compare each metric in performance.current.json against performance.baseline.json:

# Pseudocode
for metric in metrics:
    baseline_value = baseline[metric]
    current_value = current[metric]
    change_percent = ((current_value - baseline_value) / baseline_value) * 100
    
    if change_percent > REGRESSION_THRESHOLD:
        print(f"FAIL: {metric} regressed by {change_percent:.1f}%")
        # Enter self-correction loop
    else:
        print(f"PASS: {metric} is within threshold ({change_percent:.1f}%)")

Step 5: Self-Correction for Performance Regressions

If a regression is detected:

1. •Identify the code changes that likely caused the regression.
2. •Analyze the code for performance anti-patterns:
   • •N+1 queries
   • •Unnecessary re-renders
   • •Blocking I/O in hot paths
   • •Large memory allocations in loops
3. •Refactor the code to address the issue.
4. •Re-run the benchmarks.
5. •Repeat until all metrics are within the threshold.

Step 6: Update Baseline (Optional)

If the performance improves, you may want to update the baseline:

cp .ralph/performance.current.json .ralph/performance.baseline.json
git add .ralph/performance.baseline.json
git commit -m "chore: update performance baseline"

Configuration

Add the following to your CLAUDE.md:

## Performance Guardian

- **Benchmark Command**: `npm run benchmark`
- **Baseline File**: `.ralph/performance.baseline.json`
- **Regression Threshold**: 10%
- **Metrics**: api_response_time_p95, page_load_time, memory_usage_peak