---
name: loom-performance-optimization
description: "Use when a concrete performance claim, symptom, budget, regression, or metric needs measure-first work: baseline, bottleneck identification, optimization, remeasurement, guardrail, and evidence."
---

# loom-performance-optimization

Performance optimization is a measure-first playbook.

It records a baseline, identifies the bottleneck, changes the smallest thing that
can improve it, measures again, and preserves evidence and guards.

## Core Dependency

Use `loom-core` first. This playbook composes `loom-evidence`, `loom-research`,
`loom-specs`, `loom-tickets`, `loom-audit`, and `loom-retrospective`.

## Use This Playbook When

Use this playbook when:

- a spec or ticket names a performance budget
- users, monitoring, CI, or browser traces show slowness
- Core Web Vitals, response time, memory, CPU, bundle size, or query count matters
- a change may have introduced a regression
- optimization could add complexity and needs evidence

Skip speculative optimization without a claim, symptom, or budget.

## Route

Use this route:

```text
budget -> baseline -> identify -> fix -> remeasure -> guard -> audit
```

## Budget

Ground the performance claim:

- spec requirement or scenario
- ticket acceptance criterion
- production metric
- user report
- benchmark or baseline evidence
- operator-defined threshold

Route durable budgets or scenarios to `loom-specs`.

## Baseline

Capture before-state evidence.

Possible evidence:

- browser trace and Core Web Vitals
- Lighthouse or synthetic run
- RUM metric
- API timing
- database query log
- bundle analysis
- memory or CPU profile
- CI benchmark output
- manual reproduction with timing

Record environment, source state, dataset, viewport, network conditions, and tool
version when they affect the claim.

## Identify

Find the bottleneck before changing code.

Common areas:

- frontend bundle size or render-blocking resources
- slow LCP images or missing dimensions
- layout shift
- long main-thread tasks
- unnecessary rerenders
- request waterfalls
- unbounded fetches or pagination gaps
- N+1 queries
- missing database indexes
- synchronous work on hot paths
- memory leaks or unbounded caches
- external service latency

Use `loom-research` when tool interpretation, platform behavior, or source docs
matter.

## Fix

Change the specific bottleneck.

Keep the ticket narrow. Avoid broad rewrites unless evidence shows the bottleneck
requires them.

If a faster approach changes behavior, compatibility, quality, or architecture,
route to specs or constitution before implementing.

## Remeasure

Capture after-state evidence under comparable conditions.

Compare:

- metric value before and after
- variance or confidence limits when relevant
- secondary effects such as correctness, accessibility, security, and bundle
  impact
- what the measurement does not show

Do not claim improvement from anecdote alone.

## Guard

Add a guard when regression risk is real:

- performance test
- CI budget
- monitoring alert
- bundle-size gate
- query-count assertion
- dashboard note
- knowledge troubleshooting record

## Audit

Use `loom-audit` when optimization adds complexity, changes behavior, affects
security or compatibility, or relies on subtle evidence.

## Done Means

The performance pass is done when:

- a budget, symptom, or claim was named
- baseline and after-state evidence are comparable
- the bottleneck was identified before the fix
- improvement and limitations are explicit
- regression guard exists when useful
- added complexity was reviewed or justified in the consuming surface