---
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."
disable-model-invocation: true
---

# 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.

## Loom Routing

Common routes use these Loom skills for durable records or follow-up workflow:
`loom-evidence`, `loom-research`, `loom-specs`, `loom-tickets`, `loom-audit`,
`loom-retrospective`, and `loom-knowledge`.

Ensure the `using-loom` skill is loaded before applying this workflow.

When routing to any named Loom skill, follow that skill's procedure and guidance
completely. This playbook adds workflow pressure; it does not shorten the target
skill's requirements.

## Use This Playbook When

Use this playbook when:

- a spec or ticket names a performance budget
- users, monitoring, CI, or browser traces show slowness
- LCP, INP, CLS, 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 web vital metrics
- 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

Regression risk is real when the path is user-critical, previously regressed,
hard to remeasure manually, or protected by a named budget. If no guard is added,
record why the consuming surface can accept that risk.

## 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 risk is real, or the consuming surface records why
  no guard was added
- added complexity was reviewed or justified in the consuming surface
