Implement Optimization

Determine what format the user provided:

Format 1: Jira Task ID (contains letters + numbers, e.g., PERF-123, TRUST-456)

• Pattern: Starts with uppercase letters, followed by hyphen and numbers
• Example: PERF-123

Format 2: Module + Task Number (two parts, e.g., home 1, sbom-list 3)

• Pattern: Module name (string), space, task number
• Example: home 1 means Task #1 from home module

Format 3: Task Number Only (just a number, e.g., 1, 5)

• Pattern: Single number
• Example: 1 means Task #1 from most recent plan

Format 4: Full Plan File Path (path with #task, e.g., docs/performance/optimizations/home-plan-2026-04-09.md#task-1)

• Pattern: Contains file path
• Example: Direct path to specific task

Step 0.2 – Locate the Task

If Format 1 (Jira Task ID):

1. Try to fetch the Jira task:

   # Method A: Use jira CLI (preferred if available)
   jira issue view {{task-id}} --plain
   
   # Method B: Use Jira MCP (if configured)
   # mcp__atlassian__getJiraIssue(task-id)
   

2. Verify it's a performance optimization task:

   • Check labels include performance-optimization
   • Should be linked to a Feature issue or have description format from agentune
   • If missing label, warn user but continue (might be manually created)

3. Extract task details from the Jira description:

   • Look for structured sections created by plan-optimization skill
   • Parse markdown sections for: Module, Files to Modify, Implementation Notes, etc.

If Format 2 (Module + Task Number):

1. Find the module's latest plan:

   # Look for most recent plan file for this module
   ls -t docs/performance/optimizations/{{module-name}}-plan-*.md | head -1
   

2. Load the plan file and extract Task #{{number}}

If Format 3 (Task Number Only):

1. Find the most recent plan file (any module):

   ls -t docs/performance/optimizations/*-plan-*.md | head -1
   

2. Extract the module name from the filename

   • Example: home-plan-2026-04-09.md → module is home

3. Inform the user:

   Using Task #{{number}} from {{module-name}} plan (most recent plan found)
   Plan file: {{plan-path}}
   
   Is this correct? (yes/no)
   

4. Wait for user confirmation before proceeding

If Format 4 (Full Plan File Path):

1. Read the specified plan file directly
2. Extract the task section specified after # (e.g., #task-1)

Step 0.3 – Parse Task Details

Regardless of source (Jira or plan file), extract these required fields:

Required Fields:

• Module: Which page/module is being optimized (e.g., home, sbom-list)
• Optimization Type: Frontend / Backend / Integration
• Description: What the optimization does and why

Implementation Details:

• Files to Modify: List of existing files to change (with file paths)
• Files to Create: List of new files to add (e.g., performance tests)
• Implementation Notes: Detailed approach, code snippets, references

Performance Validation:

• Baseline Metrics: Current measurements (e.g., "Page load: 71ms")
• Target Metrics: Expected after optimization (e.g., "Page load: 35ms")
• Performance Test Requirements: How to measure and assert the improvement

Quality Assurance:

• Acceptance Criteria: Checklist of success conditions
• Regression Prevention: Which existing tests must still pass

Example parsed task:

Module: home
Type: Integration
Description: Create vulnerability summary endpoint to eliminate N+1 and over-fetching

Files to Modify:
- Backend: modules/fundamental/src/sbom/endpoints/mod.rs
- Frontend: client/src/app/queries/sboms.ts
- Frontend: client/src/app/hooks/domain-controls/useVulnerabilitiesOfSbom.ts

Baseline: 13 API calls, 515KB payload, 143 DB queries
Target: 1 API call, 1KB payload, 4 DB queries

Performance Test: Measure API calls and payload size on dashboard load

Step 0.4 – Validate and Confirm

Before proceeding, present the task summary to the user:

📋 Task Identified: {{optimization-name}}

**Module**: {{module-name}}
**Type**: {{Frontend/Backend/Integration}}
**Impact**: {{High/Medium/Low}}

**What will be changed**:
{{list-of-files}}

**Expected improvement**:
- {{baseline-metric}}: {{value}} → {{target-value}} ({{improvement}}%)

**Estimated effort**: {{effort-estimate}}

Ready to implement this optimization? (yes/no)

If user says no, stop and ask for clarification.

If any required field is missing from the task description, stop and inform the user:

⚠️ Task description is incomplete. Missing: {{missing-fields}}

Please update the task or provide these details to continue.

Step 1 – Load Baseline and Target Metrics

Extract from task description:

• Baseline metrics: Current measurements before optimization
• Target metrics: Expected measurements after optimization
• Measurement method: How to capture the metric (e.g., Navigation Timing API, bundle analysis)

Store these for use in performance test creation and validation.

Step 2 – Understand Code Context

For each file in "Files to Modify":

Use Serena (if available)

1. Get overview: get_symbols_overview(file_path) to see structure
2. Read symbols: find_symbol(symbol_name, include_body=true) to read implementation
3. Find references: find_referencing_symbols(symbol_name) to understand usage
4. Check patterns: Look at sibling files for established patterns

Fallback to Read/Grep

If Serena is unavailable:

1. Use Read to read the full file
2. Use Grep to find related patterns
3. Use Glob to find sibling files

Identify Reusable Code

Check if the Implementation Notes list reusable utilities or helpers:

• If yes, locate them and plan to use them
• If no, search for similar functionality that could be reused
• Prefer reusing existing code over creating new implementations

Find Existing Patterns

Locate sibling files that serve similar purposes:

• For components: other pages with similar features
• For hooks: other query hooks or custom hooks
• For backend: other endpoint handlers

Understand the patterns used so the optimization matches existing code style.

Step 3 – Implement Optimization

Follow the approach from Implementation Notes.

Use Symbolic Editing (Preferred)

If Serena is available:

• replace_symbol_body(file_path, symbol_name, new_body) - Rewrite function/component
• insert_after_symbol(file_path, symbol_name, code) - Add new code
• insert_before_symbol(file_path, symbol_name, code) - Add new code
• rename_symbol(file_path, old_name, new_name) - Rename with auto-update references

Use Edit/Write (Fallback)

If Serena is unavailable:

• Use Edit to modify existing files
• Use Write to create new files
• Ensure exact indentation and formatting match existing code

Implementation Guidelines

Frontend Optimizations:

• Add React.memo: Wrap component export with React.memo(Component)
• Add useCallback: Move inline functions to useCallback hooks
• Add useMemo: Wrap expensive calculations with useMemo
• Lazy-load: Convert imports to React.lazy(() => import('...'))
• Virtualization: Integrate react-window or react-virtual
• Debouncing: Wrap input handlers with debounce utility

Backend Optimizations:

• Add pagination: Implement limit/offset or cursor-based pagination
• Field filtering: Add fields query parameter to select specific fields
• Batching: Convert multiple endpoints to batch endpoint
• Caching: Add cache headers or in-memory caching layer

Integration Optimizations:

• Parallel requests: Use Promise.all() instead of sequential awaits
• Batching: Combine related requests into single call
• Optimistic updates: Update UI immediately, sync with server async

Follow Existing Conventions

Match patterns from sibling files:

• Naming conventions
• Import organization
• Error handling patterns
• Code structure

Step 4 – Add Performance Test

Create a Playwright performance test in e2e/tests/performance/{{module-name}}.test.ts.

Test Structure

import { test, expect } from "@playwright/test";

test.describe("{{module-name}} performance", () => {
  test("{{optimization-name}} achieves target {{metric}}", async ({ page }) => {
    // Baseline values
    const baseline{{Metric}} = {{baseline-value}};
    const targetImprovement = {{percent}}; // e.g., 0.3 for 30%
    const target{{Metric}} = baseline{{Metric}} * (1 - targetImprovement);
    
    // Navigate to page
    await page.goto("/{{module-path}}");
    
    // Wait for page to fully load
    await page.waitForLoadState("networkidle");
    
    // Capture performance metrics
    const metrics = await page.evaluate(() => {
      const nav = performance.getEntriesByType("navigation")[0] as PerformanceNavigationTiming;
      return {
        loadTime: nav.loadEventEnd - nav.fetchStart,
        timeToInteractive: nav.domInteractive - nav.fetchStart,
        // ... other metrics based on optimization type
      };
    });
    
    // Assert target is met
    expect(metrics.{{metric}}).toBeLessThan(target{{Metric}});
    expect(metrics.{{metric}}).toBeGreaterThan(0); // sanity check
  });
});

Metric-Specific Tests

For bundle size optimizations:

const scripts = await page.evaluate(() => {
  return performance.getEntriesByType("resource")
    .filter(r => r.initiatorType === "script")
    .reduce((sum, s) => sum + s.transferSize, 0);
});
expect(scripts).toBeLessThan(targetBundleSize);

For API call count optimizations:

const apiCalls: string[] = [];
page.on('response', (response) => {
  if (response.url().includes('/api/')) {
    apiCalls.push(response.url());
  }
});

await page.goto("/{{module-path}}");
await page.waitForLoadState("networkidle");

expect(apiCalls.length).toBeLessThanOrEqual(targetCallCount);

For response size optimizations:

let totalTransfer = 0;
page.on('response', async (response) => {
  if (response.url().includes('/api/')) {
    const buffer = await response.body();
    totalTransfer += buffer.length;
  }
});

await page.goto("/{{module-path}}");
await page.waitForLoadState("networkidle");

expect(totalTransfer).toBeLessThan(targetTransferSize);

Step 5 – Run Performance Test

Execute the performance test:

npm run e2e:test -- e2e/tests/performance/{{module-name}}.test.ts

If test passes:

• Record the actual measured value
• Proceed to Step 6

If test fails:

• Capture the actual vs target values
• Investigate why the target was not met
• Options:
  1. Adjust the implementation to achieve target
  2. Re-evaluate the target if it was unrealistic
  3. Ask the user for guidance
• Do NOT proceed until the performance test passes

Step 6 – Run Regression Tests

Execute the functional tests for the module to ensure no regressions:

Run existing tests:

# Unit tests
npm test -- {{module-name}}

# Functional E2E tests
npm run e2e:test -- e2e/tests/ui/{{module-name}}/

Verify:

• All tests pass
• No new console errors or warnings
• No behavioral changes

If any test fails:

• Investigate the root cause
• Fix the regression
• Re-run tests
• Do NOT proceed until all tests pass

Step 7 – Commit Changes

Create a commit with performance metrics:

git add {{files}}

git commit -m "perf({{module}}): {{optimization-description}}

{{detailed-description-from-task}}

Baseline: {{metric}} = {{baseline-value}}
Optimized: {{metric}} = {{new-value}}
Improvement: {{percent}}%

Co-Authored-By: Claude Code <[email protected]>"

Use conventional commit format with perf type.

Include:

• Baseline value from task
• Actual measured value from performance test
• Calculated improvement percentage

Step 8 – Run Verification

Before creating a PR, run comprehensive verification using the verify-optimization skill:

/performance-analysis:verify-optimization {{module-name}}

This will:

• Run all test suites (unit, functional E2E, performance)
• Capture fresh performance measurements
• Compare against baseline and targets
• Generate verification report
• Provide PASS/PARTIAL PASS/FAIL status

Wait for verification to complete.

If verification returns PASS:

• Proceed to Step 9 to create PR
• Include verification report in PR description

If verification returns PARTIAL PASS:

• Review marginal targets with user
• Ask user: "Some targets were marginal but showed improvement. Create PR anyway?"
• If user approves, proceed to Step 9 with notes about marginal targets
• If user declines, stop and ask for next steps

If verification returns FAIL:

• DO NOT create PR
• Review failed tests and metrics with user
• Options:
  1. Fix issues and re-run from Step 3
  2. Adjust targets in optimization plan if they were unrealistic
  3. Ask user for guidance
• Only proceed to PR creation after verification passes

Step 9 – Create PR (Only After Verification Passes)

Push the branch and create a pull request:

Branch naming:

git checkout -b perf/{{module}}-{{optimization-name}}
git push -u origin perf/{{module}}-{{optimization-name}}

PR description:

Include the verification report that was generated in Step 8. Read the verification report file and use its content as the core of the PR description:

# Performance Optimization: {{optimization-name}}

## Module
{{module-name}}

## Optimization
{{description-from-task}}

## Verification Report

{{Include full content from verification report}}

{{If PARTIAL PASS, add note}}
**Note on Marginal Targets**: 
Some targets were not fully met but showed significant improvement. See details in verification report above.

## Implements

{{If Jira task: [TASK-123](task-url)}}
{{If plan file: See optimization plan: {{plan-file-path}}}}

## Verification (for reviewers)

This optimization has been pre-verified. To re-run verification:
```bash
git checkout {{branch-name}}
/performance-analysis:verify-optimization {{module-name}}

Create the PR using `gh`:
```bash
gh pr create --title "perf({{module}}): {{optimization-name}}" --body "{{pr-description}}"

Step 10 – Update Jira (If Applicable)

If the task was from Jira:

1. Add comment to task:

   • Include PR link
   • Summary of changes
   • Performance results table
   • Verification commands
   • Version footer with plugin name and version

2. Transition task:

   • Use mcp__atlassian__transitionJiraIssue to move to "In Review"

If the task was from a plan file (not Jira), skip this step.

Important Rules

• Never skip performance test validation — the optimization is not complete until the performance test passes
• Never skip regression test validation — functional correctness is more important than performance
• If the performance target cannot be met, investigate and adjust before committing
• If a regression occurs, rollback changes and re-plan the optimization
• Always use Conventional Commits format
• Include actual measured values in commit message, not just targets
• Prefer symbolic editing (Serena) over file-based editing when available
• Follow existing code patterns and conventions from sibling files