/perf

description: Structured performance investigation with baselines, profiling, and evidence-backed decisions
argument-hint: "[--resume] [--phase setup|baseline|breaking-point|constraints|hypotheses|code-paths|profiling|optimization|decision|consolidation] [--id <id>] [--scenario <text>] [--command <cmd>] [--version <ver>] [--duration <seconds>] [--runs <n>] [--aggregate <median|mean|min|max>] [--quote <text>] [--hypotheses-file <path>] [--param-env <name>] [--param-min <n>] [--param-max <n>] [--cpu <limit>] [--memory <limit>] [--change <summary>] [--verdict <continue|stop>] [--rationale <text>]"
allowed-tools: Read, Write, Edit, Task, Bash(git:*), Bash(node:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(cargo:*), Bash(go:*), Bash(pytest:*), Bash(mvn:*), Bash(gradle:*)

/perf - Performance Investigation Workflow

Run a rigorous, evidence-driven performance investigation with strict rules, baselines, and reproducible benchmarks.

Canonical Requirements

All behavior must follow:

• `docs/perf-requirements.md` (source of truth)
• `docs/perf-research-methodology.md`

Arguments

• `--resume`: Continue the latest investigation from `{state-dir}/perf/investigation.json`
• `--phase <phase>`: Force starting phase (use only when resuming)
• `--id <id>`: Set investigation id (new only)
• `--scenario <text>`: Short scenario description
• `--command <cmd>`: Benchmark command (prints PERF_METRICS markers)
• `--version <ver>`: Baseline version label
• `--duration <seconds>`: Benchmark duration override (default 60s; use smaller values for micro-benchmarks)
• `--runs <n>`: Number of runs for start-to-end benchmarks (use with median aggregation)
• `--aggregate <median|mean|min|max>`: Aggregation method for multi-run benchmarks (default median)
• `--quote <text>`: User quote to record in logs
• `--hypotheses-file <path>`: JSON file with hypothesis list (for hypotheses phase)
• `--param-env <name>`: Env var for breaking-point value (default PERF_PARAM_VALUE)
• `--param-min <n>`: Breaking-point min value (default 1)
• `--param-max <n>`: Breaking-point max value (default 500)
• `--cpu <limit>`: Constraint CPU limit (default 1)
• `--memory <limit>`: Constraint memory limit (default 1GB)
• `--change <summary>`: Optimization change summary
• `--verdict <continue|stop>`: Decision verdict
• `--rationale <text>`: Decision rationale

Phase 1: Initialize Investigation State

const { getPluginRoot } = require('@awesome-slash/lib/cross-platform');
const pluginRoot = getPluginRoot('perf');
if (!pluginRoot) { console.error('Error: Could not locate perf plugin root'); process.exit(1); }
const investigationState = require(`${pluginRoot}/lib/perf/investigation-state.js`);
const baselineStore = require(`${pluginRoot}/lib/perf/baseline-store.js`);
const benchmarkRunner = require(`${pluginRoot}/lib/perf/benchmark-runner.js`);
const breakingPointRunner = require(`${pluginRoot}/lib/perf/breaking-point-runner.js`);
const constraintRunner = require(`${pluginRoot}/lib/perf/constraint-runner.js`);
const profilingRunner = require(`${pluginRoot}/lib/perf/profiling-runner.js`);
const optimizationRunner = require(`${pluginRoot}/lib/perf/optimization-runner.js`);
const consolidation = require(`${pluginRoot}/lib/perf/consolidation.js`);
const checkpoint = require(`${pluginRoot}/lib/perf/checkpoint.js`);
const argumentParser = require(`${pluginRoot}/lib/perf/argument-parser.js`);
const codePaths = require(`${pluginRoot}/lib/perf/code-paths.js`);
const repoMap = require(`${pluginRoot}/lib/repo-map`);
const fs = require('fs');

const args = argumentParser.parseArguments('$ARGUMENTS');
const options = {
  resume: false,
  phase: null,
  id: null,
  scenario: '',
  command: '',
  version: '',
  duration: null,
  runs: null,
  aggregate: '',
  quote: '',
  hypothesesFile: '',
  paramEnv: 'PERF_PARAM_VALUE',
  paramMin: 1,
  paramMax: 500,
  cpu: '1',
  memory: '1GB',
  change: '',
  verdict: '',
  rationale: ''
};

for (let i = 0; i < args.length; i++) {
  const arg = args[i];
  if (arg === '--resume') options.resume = true;
  else if (arg === '--phase' && args[i + 1]) options.phase = args[++i];
  else if (arg === '--id' && args[i + 1]) options.id = args[++i];
  else if (arg === '--scenario' && args[i + 1]) options.scenario = args[++i];
  else if (arg === '--command' && args[i + 1]) options.command = args[++i];
  else if (arg === '--version' && args[i + 1]) options.version = args[++i];
  else if (arg === '--duration' && args[i + 1]) options.duration = Number(args[++i]);
  else if (arg === '--runs' && args[i + 1]) options.runs = Number(args[++i]);
  else if (arg === '--aggregate' && args[i + 1]) options.aggregate = args[++i];
  else if (arg === '--quote' && args[i + 1]) options.quote = args[++i];
  else if (arg === '--hypotheses-file' && args[i + 1]) options.hypothesesFile = args[++i];
  else if (arg === '--param-env' && args[i + 1]) options.paramEnv = args[++i];
  else if (arg === '--param-min' && args[i + 1]) options.paramMin = Number(args[++i]);
  else if (arg === '--param-max' && args[i + 1]) options.paramMax = Number(args[++i]);
  else if (arg === '--cpu' && args[i + 1]) options.cpu = args[++i];
  else if (arg === '--memory' && args[i + 1]) options.memory = args[++i];
  else if (arg === '--change' && args[i + 1]) options.change = args[++i];
  else if (arg === '--verdict' && args[i + 1]) options.verdict = args[++i];
  else if (arg === '--rationale' && args[i + 1]) options.rationale = args[++i];
}

const cwd = process.cwd();
const allowedPhases = investigationState.PHASES;
if (options.phase && !allowedPhases.includes(options.phase)) {
  console.error(`Invalid phase: ${options.phase}. Allowed: ${allowedPhases.join(', ')}`);
  process.exit(1);
}

let state = investigationState.readInvestigation(cwd);
if (options.resume) {
  if (!state) {
    console.error('No active investigation found. Run /perf without --resume first.');
    process.exit(1);
  }
} else {
  state = investigationState.initializeInvestigation({