/performance-optimization

description: "Orchestrate end-to-end application performance optimization from profiling to monitoring"
argument-hint: "<application or service> [--focus latency|throughput|cost|balanced] [--depth quick-wins|comprehensive|enterprise]"

Performance Optimization Orchestrator

CRITICAL BEHAVIORAL RULES

You MUST follow these rules exactly. Violating any of them is a failure.

1. **Execute steps in order.** Do NOT skip ahead, reorder, or merge steps. 2. **Write output files.** Each step MUST produce its output file in `.performance-optimization/` before the next step begins. Read from prior step files — do NOT rely on context window memory. 3. **Stop at checkpoints.** When you reach a `PHASE CHECKPOINT`, you MUST stop and wait for explicit user approval before continuing. Use the AskUserQuestion tool with clear options. 4. **Halt on failure.** If any step fails (agent error, test failure, missing dependency), STOP immediately. Present the error and ask the user how to proceed. Do NOT silently continue. 5. **Use only local agents.** All `subagent_type` references use agents bundled with this plugin or `general-purpose`. No cross-plugin dependencies. 6. **Never enter plan mode autonomously.** Do NOT use EnterPlanMode. This command IS the plan — execute it.

Pre-flight Checks

Before starting, perform these checks:

1. Check for existing session

Check if `.performance-optimization/state.json` exists:

• If it exists and `status` is `"in_progress"`: Read it, display the current step, and ask the user:

  Found an in-progress performance optimization session:
  Target: [name from state]
  Current step: [step from state]

  1. Resume from where we left off
  2. Start fresh (archives existing session)

• If it exists and `status` is `"complete"`: Ask whether to archive and start fresh.

2. Initialize state

Create `.performance-optimization/` directory and `state.json`:

{
  "target": "$ARGUMENTS",
  "status": "in_progress",
  "focus": "balanced",
  "depth": "comprehensive",
  "current_step": 1,
  "current_phase": 1,
  "completed_steps": [],
  "files_created": [],
  "started_at": "ISO_TIMESTAMP",
  "last_updated": "ISO_TIMESTAMP"
}

Parse `$ARGUMENTS` for `--focus` and `--depth` flags. Use defaults if not specified.

3. Parse target description

Extract the target description from `$ARGUMENTS` (everything before the flags). This is referenced as `$TARGET` in prompts below.

---

Phase 1: Performance Profiling & Baseline (Steps 1–3)

Step 1: Comprehensive Performance Profiling

Use the Task tool to launch the performance engineer:

Task:
  subagent_type: "application-performance-performance-engineer"
  description: "Profile application performance for $TARGET"
  prompt: |
    Profile application performance comprehensively for: $TARGET.

    Generate flame graphs for CPU usage, heap dumps for memory analysis, trace I/O operations,
    and identify hot paths. Use APM tools like DataDog or New Relic if available. Include database
    query profiling, API response times, and frontend rendering metrics. Establish performance
    baselines for all critical user journeys.

    ## Deliverables
    1. Performance profile with flame graphs and memory analysis
    2. Bottleneck identification ranked by impact
    3. Baseline metrics for critical user journeys
    4. Database query profiling results
    5. API response time measurements

    Write your complete profiling report as a single markdown document.

Save the agent's output to `.performance-optimization/01-profiling.md`.

Update `state.json`: set `current_step` to 2, add step 1 to `completed_steps`.

Step 2: Observability Stack Assessment

Read `.performance-optimization/01-profiling.md` to load profiling context.

Use the Task tool:

Task:
  subagent_type: "application-performance-observability-engineer"
  description: "Assess observability setup for $TARGET"
  prompt: |
    Assess current observability setup for: $TARGET.

    ## Performance Profile
    [Insert full contents of .performance-optimization/01-profiling.md]

    Review existing monitoring, distributed tracing with OpenTelemetry, log aggregation,
    and metrics collection. Identify gaps in visibility, missing metrics, and areas needing
    better instrumentation. Recommend APM tool integration and custom metrics for
    business-critical operations.

    ## Deliverables
    1. Current observability assessment
    2. Instrumentation gaps identified
    3. Monitoring recommendations
    4. Recommended metrics and dashboards

    Write your complete assessment as a single markdown document.

Save the agent's output to `.performance-optimization/02-observability.md`.

Update `state.json`: set `current_step` to 3, add step 2 to `completed_steps`.

Step 3: User Experience Analysis

Read `.performance-optimization/01-profiling.md`.

Use the Task tool:

Task:
  subagent_type: "application-performance-performance-engineer"
  description: "Analyze user experience metrics for $TARGET"
  prompt: |
    Analyze user experience metrics for: $TARGET.

    ## Performance Baselines
    [Insert contents of .performance-optimization/01-profiling.md]

    Measure Core Web Vitals (LCP, FID, CLS), page load times, time to interactive,
    and perceived performance. Use Real User Monitoring (RUM) data if available.
    Identify user journeys with poor performance and their business impact.

    ## Deliverables
    1. Core Web Vitals analysis
    2. User journey performance report
    3. Business impact assessment
    4. Prioritized improvement opportunities

    Write your complete analysis as a single markdown document.

Save the agent's output to `.performance-optimization/03-ux-analysis.md`.

Update `state.json`: set `current_step` to "checkpoint-1", add step 3 to `completed_steps`.

---

PHASE CHECKPOINT 1 — User Approval Required

You MUST stop here and present the profiling results for review.

Display a summar