# Optimize

> Run measured optimization loops. Use for latency, throughput, resource, cost, build, or query improvements that need proof.

- Skill: `mopeyjellyfish/optimize` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add mopeyjellyfish/optimize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mopeyjellyfish/optimize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: mopeyjellyfish (https://skillmd.com/u/mopeyjellyfish)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mopeyjellyfish/optimize

---


# Optimize With Measurement

`$fw:optimize` is Flywheel's optimization workflow.

Use it when the question is:

- what is actually slow, expensive, noisy, or inefficient?
- which change improves the metric without breaking correctness?
- how do we prove the improvement against real telemetry or a trustworthy local
  harness?

This is not a "spray tweaks and hope" skill. It is a measurement-first loop.

## Interaction Method

Follow `../references/host-interaction-contract.md`.

Call the exact host question tool named in
`../references/host-interaction-contract.md` when that tool is available. Do
not ask for raw `1/2/3` replies when the host already offers a choice surface.

When the workflow spans multiple material steps, use the host task-tracking
tool named in `../references/host-interaction-contract.md` to create and
maintain a short task list.

Ask one question at a time. When multiple measurement paths are viable, present
the recommended label first and rely on the host's native freeform final path
when it exists.

## Input

<optimization_input> #$ARGUMENTS </optimization_input>

Interpret the input as one of:

- a concrete optimization goal
- a known hotspot, service, query path, or component
- a latency, throughput, cost, or saturation problem
- an existing optimization note or spec

If the input is blank, ask what should be optimized and which outcome matters.

## Reference Loading Map

Do not preload every reference. Load only what the current phase needs:

- Read `references/provider-selection.md` when choosing the measurement source.
- Read `references/measurement-contract.md` when building the optimization
  contract.
- Read `references/datadog-path.md` only when the Datadog path is selected.
- Read `references/lgtm-path.md` only when the OTel-native path is selected.
- Read `references/optimization-loop.md` only when execution planning begins.
- Read `../commit/references/evidence-bundle.md` only when a measured result
  should be handed off into `$fw:review` or `$fw:commit`.
- Read `../observability/references/service-readiness-matrix.md` only when the
  optimization target is runtime-risky or blast-radius-sensitive.

## Execution Notes

Keep the stable optimization scaffold first, gather repo and telemetry truth
before forming hypotheses, and prefer one measured improvement over a bag of
speculative micro-tweaks.

- keep the measurement source explicit
- state the metric, guardrails, and stop criteria before changing code
- use serial experiments by default
- keep changes small enough that the metric movement can still be attributed

## Core Principles

1. **No optimization without a metric** - define what better means before
   editing code.
2. **Use the repo's real observability front door** - Datadog, an OTel-native
   backend surface, or a local harness. Do not invent a telemetry source when
   the project already has one.
3. **Correctness and reliability are guardrails, not optional follow-ups** -
   performance wins that raise error rate, break ordering, or widen blast
   radius do not count as wins.
4. **Prefer hybrid proof when available** - use local benchmarks, local
   profiles, or a local observability stack for fast iteration, then validate
   in a shared environment when the change is runtime-facing.
5. **One experiment, one conclusion** - small deltas beat giant rewrites when
   the goal is attribution.

## Workflow

### Phase 0: Classify The Optimization Target

Decide what category of optimization is in scope:

- request or endpoint latency
- job, queue, or batch throughput
- query or storage efficiency
- CPU, memory, or allocation pressure
- cache hit rate or invalidation churn
- build, test, or developer loop performance
- infrastructure spend or saturation

Also classify whether the target is:

- **local-only** - build, benchmark, or profile work can be proven on the
  machine
- **runtime-facing** - service behavior must be proven against telemetry
- **hybrid** - local measurement is fast, but a shared environment is needed to
  confirm the result matters

### Phase 1: Touch Grass

Build an optimization ledger from repo truth:

- read `AGENTS.md` and `CLAUDE.md` when present
- inspect relevant manifests, scripts, CI workflows, benchmark harnesses, load
  tests, and profiling configs
- inspect nearby code and tests for the target path
- inspect the active repo's `docs/solutions/` for prior performance or
  reliability learnings
- read `.context/flywheel/setup-ledger.md` when present
- inspect observability config, instrumentation libraries, dashboards, monitor
  references, saved queries, and environment variables

Capture:

- the target code path or service boundary
- the current likely bottleneck and alternative hypotheses
- correctness guardrails and reliability risks
- existing measurement surfaces
- whether the repo already appears Datadog-first, OTel-native-first, or
  local-only
- which environments are actually observable: local dev stack, shared
  non-production, production, or only a subset

If the optimization target is runtime-risky, read
`../observability/references/service-readiness-matrix.md` and keep the
applicable dimensions visible while optimizing.

### Phase 2: Choose The Measurement Source

Read `references/provider-selection.md`.

Use repo evidence plus any setup ledger to choose one of these paths:

- **Hybrid local + shared** (recommended when both a fast local harness and a
  trustworthy shared measurement environment exist)
- **Datadog-backed measurement**
- **OTel-native backed measurement**
- **Local-only benchmark/profile/stack**
- Freeform path when the repo needs a different measurement posture

Selection rules:

- choose **Datadog-backed** when Datadog appears to be the operational system
  of record and the user has Datadog MCP or equivalent read access
- choose **OTel-native backed** when the repo is OTel-first or Grafana,
  Prometheus or Mimir, Loki, Tempo, Pyroscope, or collector-backed dashboards
  are the real support surfaces
- choose **Local-only** when remote access is unavailable, the code is not yet
  deployed, or the hotspot is purely local
- choose **Hybrid** when local measurement is useful for rapid iteration and a
  shared environment is available to validate the real-world effect

If both Datadog and OTel-native surfaces are plausible, first verify which
backend is the source of truth for this target. Then pin the environment
separately: local dev stack, shared non-production, or production.

### Phase 3: Build The Measurement Contract

Read `references/measurement-contract.md`.

Before making changes, define:

1. **Primary metric** - the number that decides whether the change won
2. **Guardrails** - correctness, error rate, resource caps, saturation, or
   reliability constraints that must not regress
3. **Measurement source** - local benchmark, Datadog query, PromQL, TraceQL,
   log query, profile, or dashboard
4. **Workload / sample** - the request mix, traffic window, fixture, or batch
5. **Observation window** - enough time to reduce noise and avoid mixed
   rollouts
6. **Version / rollout binding** - how you will isolate the experiment from
   unrelated traffic or deploys
7. **Stop criteria** - what counts as success, failure, or insufficient signal

If you cannot define a trustworthy baseline, stop and build or identify the
measurement surface first.

### Phase 4: Load The Path-Specific Guidance

If the selected path is Datadog, read `references/datadog-path.md`.

If the selected path is OTel-native backed, read `references/lgtm-path.md`.

Use that guidance to pin:

- exact tags, labels, services, environments, and versions
- the metrics, traces, logs, and profiles that matter most
- the safest query surfaces for comparing before vs after

### Phase 5: Plan The Optimization Loop

Read `references/optimization-loop.md`.

Prefer serial iteration:

1. baseline
2. hypothesis
3. smallest credible change
4. local checks and correctness tests
5. measurement
6. keep, revert, or revise

Only parallelize experiments when:

- the code paths are isolated
- the measurements are independent
- the user explicitly wants parallel work

### Phase 6: Execute And Measure

For each experiment:

- state the hypothesis in one sentence
- make the smallest change that can move the metric
- run correctness checks before treating a metric move as real
- measure against the contract
- compare against baseline and guardrails
- record what changed, what moved, and whether the hypothesis held

Use local worktrees when isolated iteration will reduce confusion or protect
the current checkout.

If the change survives the optimization gate, route through `$fw:review` and
`$fw:commit` before calling it complete.

When the measurement result should feed later stages, create or update a shared
evidence bundle under:

```text
.context/flywheel/evidence/<bundle-id>/
```

Keep the shared summary focused on:

- baseline
- guardrails
- measurement source
- winning change or current best direction
- the exact query, benchmark, dashboard, or profile name to rerun

Keep bulky raw traces, profiles, or benchmark outputs in their native local
location and reference them from the bundle instead of copying them.

## Output Contract

Return a concise optimization brief:

1. **Target** - what is being optimized
2. **Chosen measurement backend** - Datadog, OTel-native, local-only, or hybrid
3. **Chosen environment** - local dev stack, shared non-production,
   production, or mixed
4. **Baseline and guardrails**
5. **Top hypotheses**
6. **Experiment posture** - serial or parallel, and why
7. **Winning change or current best direction**
8. **Residual risks or missing signal**
9. **Evidence bundle** - shared bundle path when one was created, otherwise
   `not created`
10. **Next Flywheel handoff** - `$fw:work`, `$fw:review`, `$fw:commit`, or
    another optimization iteration

---

## Included References

@./references/provider-selection.md
@./references/measurement-contract.md
@./references/datadog-path.md
@./references/lgtm-path.md
@./references/optimization-loop.md
@../commit/references/evidence-bundle.md