Skip to content
Skills Library
Programming · Building & coding

pair-optimize

/pair-optimize

Use when the user wants a measured speedup or cost reduction for something concrete and runnable — a DuckDB/SQL query, a hot Python path, an endpoint, a pipeline step — with a second agent (Claude ↔ Codex) challenging the numbers, rather than vibes-based tuning. Also use when invoked as the peer ("Resume the pair-optimize skill"). Hard rule — no optimization is kept unless it is measured faster/cheaper AND produces output identical to the baseline.

Repository
skills ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
7
Scripts
2
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 2 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: evals/handoff-parsing.sh, reference/handoff.sh

What it does and when to use it

Use when the user wants a measured speedup or cost reduction for something concrete and runnable — a DuckDB/SQL query, a hot Python path, an endpoint, a pipeline step — with a second agent (Claude ↔ Codex) challenging the numbers, rather than vibes-based tuning. Also use when invoked as the peer ("Resume the pair-optimize skill"). Hard rule — no optimization is kept unless it is measured faster/cheaper AND produces output identical to the baseline.

Triggers from the description

Resume the pair-optimize skill

Arguments

/pair-optimize <target> [--from-session] [--number n] [--model high|xhigh]
Original author description

Use when the user wants a measured speedup or cost reduction for something concrete and runnable — a DuckDB/SQL query, a hot Python path, an endpoint, a pipeline step — with a second agent (Claude ↔ Codex) challenging the numbers, rather than vibes-based tuning. Also use when invoked as the peer ("Resume the pair-optimize skill"). Hard rule — no optimization is kept unless it is measured faster/cheaper AND produces output identical to the baseline.

How it works

  1. The contract (read this first)
  2. TL;DR for a cold-woken peer
  3. Overview
  4. Two roles
  5. When to use
  6. Round protocol — one allowed action per round
  7. Measurement & equivalence techniques (hard-won)
  8. Surfacing rounds in chat
  9. Shared state in .optimize/
  10. Entry modes
Original SKILL.md headings · 228 lines, 3,585 words
SKILL.md preview
---
name: pair-optimize
description: Use when the user wants a measured speedup or cost reduction for something concrete and runnable — a DuckDB/SQL query, a hot Python path, an endpoint, a pipeline step — with a second agent (Claude ↔ Codex) challenging the numbers, rather than vibes-based tuning. Also use when invoked as the peer ("Resume the pair-optimize skill"). Hard rule — no optimization is kept unless it is measured faster/cheaper AND produces output identical to the baseline.
argument-hint: "<target> [--from-session] [--number n] [--model high|xhigh]"
---

# pair-optimize

## The contract (read this first)

**No optimization is kept unless BOTH hold:**

1. **Measured better** — faster or cheaper than the baseline, on representative data, with enough repetitions to beat noise (report median + spread, not a single run).
2. **Provably identical output** — the optimized version produces the same result as the baseline (same rows/values for SQL; same return value / passing tests for Python).

A candidate that can't be measured is **not** "probably fine" — it is labeled `UNVERIFIED` and the baseline stays. Never fabricate or estimate numbers; if the target can't be run (no representative data, no harness), say so and fall back to static analysis explicitly marked unverified.

## TL;DR for a cold-woken peer

You were invoked via `codex exec` or `claude -p` with *"Resume the pair-optimize skill. Read .optimize/STATE.md..."*. You are a **one-shot peer**: you do exactly ONE round (an even round — R2, R4, …) and exit. Do this:

1. `cat .optimize/STATE.md .optimize/TARGET.md .optimize/USER_NOTES.md` — orient.
2. Confirm `STATUS: WAITING: <you>` and read `ROUND:` + `ROUNDS:`. You are B; even rounds are yours — find whether this one is a **challenge** or a **measurement audit** in the [round-type table](#overview).
3. **Re-run the numbers yourself** where you can — don't trust A's benchmark on faith; that's the entire point of a second agent.
4. Write `R<ROUND>.md`, then update `STATE.md`: set `STATUS: WAITING: <A's CLI name>` (the value of STATE.md's `A:` line, e.g. `WAITING: claude` — never the literal letter "A") and bump `ROUND`.
5. **EXIT. Do NOT call `optimize_handoff` or `optimize_wait`.** The orchestrator is already blocked in `optimize_wait` and resumes the instant you flip `STATE.md`. If you hand off, you spawn a **duplicate orchestrator** — two instances collide on `STATE.md`. Don't be that bug.

**You never do the final round.** The final round (`ROUND == ROUNDS`) is always the orchestrator's synthesis. Only the orchestrator runs `optimize_handoff` + `optimize_wait`; see [Two roles](#two-roles) and [Handoff](#handoff).

No session memory across turns. State lives in `.optimize/`. Templates for every file are in [reference/file-formats.md](reference/file-formats.md).

## Overview

The default session is **5 rounds**. `--number n` sets the **round cap** (`ROUNDS:` in `STATE.md`) — a max, since [early termination](#early-termination) can finish sooner; see [Flags](#flags). The 5-round shape:

| Round | Actor | Action | Output |
|---|---|---|---|
| **R1** | A (orchestrator) | **Baseline + candidates.** Measure the target, profile to find the real bottleneck, propose ranked candidate optimizations (C1, C2, …) with hypothesized wins. **No code changes yet.** | `R1.md` |
| **R2** | B (peer, one-shot) | **Challenge.** Is the baseline fair? the bottleneck real? each candidate worth it / correctness-safe? Name the measurement that settles each. | `R2.md` |
| **R3** | A (orchestrator) | **Implement + benchmark.** Apply surviving candidate(s), benchmark vs baseline on the same harness, prove output equality. Per candidate: `Result: kept\|reverted` + numbers. | `R3.md` (+ code in repo) |
| **R4** | B (peer, one-shot) | **Audit the measurement.** Warm-cache artifact? representative data? enough iterations? correctness actually held? win worth the complexity? Per candidate: `Verdict: keep\|revert\|doubt`. | `R4.md` |
| **R5** | A (orchestrator) | **Synthesize + ask user.** Net result with numbers, correctness statement, complexity tradeoffs, what to keep. | `R5.md` — user reads this |

**Round-type rule — canonical; every other mention of the round math points here.** Given `ROUND` and `ROUNDS` (= `n`, forced odd so A is both the first measurer and the last synthesizer), first matching row wins:

| Condition | Actor | Round type |
|---|---|---|
| `ROUND == 1` | A | Baseline + candidates |
| `ROUND == ROUNDS` | A | Synthesize + ask user |
| `ROUND == ROUNDS-1` and `ROUNDS >= 5` | B | Audit the measurement |
| other even `ROUND` | B | Challenge |
| other odd `ROUND` | A | Implement + benchmark |

At `n=5` this is exactly the table above; at `n=7` it adds another implement/challenge cycle. **At `n=3`** there is no audit and no interior implement round — the single B round is a challenge, and A may fold implement+benchmark into the final synthesis round (the contract still holds: only measured wins are kept) but must note in the synthesis that those numbers received no B audit.

After the final round, `STATUS: AWAITING_USER` and the loop stops. The user's reply (apply / iterate / cancel) closes the session.

## Two roles

The loop has an **asymmetry that prevents duplicate instances** — internalize it.

- **Orchestrator = A** = the interactive session that ran `/pair-optimize`. Alive for the whole session; does the odd rounds (R1, R3, … and the final round). After each non-final round it spawns the peer (`optimize_handoff B`) and blocks in `optimize_wait` until the peer flips `STATE.md` back. After the final round it stops.
- **Peer = B** = a *fresh, headless, one-shot* instance, cold-woken by `optimize_handoff`. It does exactly one round (an even round), flips `STATUS: WAITING: <A's CLI name>`, and **exits**. It never calls `optimize_handoff` and never calls `optimize_wait`.

**Why:** `optimize_handoff` always *spawns a new instance* of the named peer. If B hands back with `optimize_handoff A`, it spawns a **second A** while the original is still alive in `optimize_wait` — both act, both write the round, both collide on `STATE.md`. Safe shape: **only the orchestrator hands off and waits; the peer flips-and-exits.**

## When to use

- `/pair-optimize "<target: a query, function, endpoint, or pipeline step>"` (fresh) or `/pair-optimize` (resume).
- You have something concrete and **runnable** to optimize, and a way to feed it representative data.
- You want a measured speedup/cost-cut with a second agent guarding against fake wins and correctness regressions.
- You were invoked as the peer by the active agent.

**Don't use for:** broad architecture redesign (brainstorm it first), correctness bugs (that's debugging, not optimization), un-runnable targets (nothing to measure → the contract can't hold), or solo micro-tweaks you'd just commit.

## Round protocol — one allowed action per round

Each round is narrow on purpose. **Templates for each round file are in [reference/file-formats.md](reference/file-formats.md).** Figure out which round type you're doing from the round-type table in the [Overview](#overview) — the labels below name the type, not a round number.

- **Baseline + candidates (A).** Read `TARGET.md`. Build/identify a measurement harness and record the **baseline number** (SQL: wall-time + rows/bytes scanned via `EXPLAIN ANALYZE`; Python: median over N runs via `timeit`/`pytest-benchmark`, plus a **sampling** profile for the real hotspot — see [Measurement & equivalence techniques](#measurement--equivalence-techniques-hard-won)). Identify the **real bottleneck with evidence** — not a guess. Propose ranked candidates (C1, C2, …), each with the mechanism of the expected win and any correctness risk. A ranked menu of candidates — each with its mechanism and the adversarial input that breaks it — lives in [reference/python-toolbox.md](reference/python-toolbox.md) (Python: profiler commands, the candidate menu, the memory axis) and [reference/sql-toolbox.md](reference/sql-toolbox.md) (SQL/DuckDB: plan-reading, scan/join rewrites, the duplicate-row equivalence trap). Draw from the one that fits the target, but treat every entry as a hypothesis to measure, not a fact. Do **not** change code yet.
- **Challenge (B).** Reproduce A's baseline where you can. Attack: is the data representative? the metric the right one? the bottleneck actually dominant (or a contention artifact — see [techniques](#measurement--equivalence-techniques-hard-won))? Is each candidate premature/cargo-cult, and will it move the *measured* metric? (The micro-op tier in [reference/python-toolbox.md](reference/python-toolbox.md) — list-comp-for-loop, local-var hoisting, inlining — is usually neutral; demand a measured win before any of them survives.) **Hunt for the input distribution or invariant where the candidate's output diverges** — identical on sample data is NOT behaviour-preservation (duplicate/overlapping keys, NULLs, empty input, dtype shifts, ordering). For each, name the measurement that proves or kills it. Numbered challenges. Then flip `STATUS: WAITING: <A's CLI name>`, bump `ROUND`, **exit**.
- **Implement + benchmark (A).** Apply the surviving candidate(s) in the repo. Benchmark each against the baseline on the **same harness and data**, enough iterations to beat noise. **Prove output equality** (SQL: `EXCEPT ALL` both directions / `ORDER BY`+hash / row-count+checksum; Python: identical return or existing tests pass) and **commit that equality check to `bench/`** as a re-runnable script, so B can independently re-execute it in R4. Per candidate write `Result: kept|reverted`, baseline→after numbers, and the correctness check. A candidate that isn't measurably better, or changes output, is **reverted**.
- **Audit the measurement (B).** For each kept candidate, attack the *measurement*, not just the idea: warm-cache/JIT artifact, contention/shared-infra variance, unrepresentative data, too few iterations vs variance. **And re-verify equality yourself, don't just critique A's proof** — the whole point of a second agent applies to *both* halves of the contract, not only the speed number. Re-run A's equivalence check from `bench/` against the candidate, and add at least one adversarial input of your own (dup/overlapping key, NULL, empty, dtype shift, reordered) comparing baseline-impl vs candidate-impl directly. If the harness can't be re-run headless, say so and downgrade to `doubt`. Decide `keep` / `revert` / `doubt` (needs re-measure). Is the win worth the added complexity? This is B's last word. Flip `STATUS: WAITING: <A's CLI name>`, set `ROUND: <n>`, **exit**.
- **Synthesize + ask (A).** Net result: which candidates to keep with their numbers and the combined effect, the correctness statement, the complexity/maintainability cost, and anything still `UNVERIFIED`. Then `STATUS: AWAITING_USER` and stop.

### Early termination

`ROUNDS` (default 5) is the max, not the requirement. Skip a round that would rubber-stamp; when in doubt, run it. Role-relative triggers (hold at any `n`):

| Trigger | What to do |
|---|---|
| A's R1 finds the target is already optimal / not the bottleneck | Skip to synthesis: report "no measured win available," recommend no change. |
| A B-challenge raises zero substantive objections | A goes ahead and benchmarks, then jumps toward synthesis. |
| Every candidate reverted (no measured win) AND no open challenge | Jump to synthesis — recommend keeping the baseline. |
| A kept a candidate with new/contested numbers | Run the next B-audit — it catches measurement artifacts. |

When skipping ahead, jump straight to the final round (`ROUND: <n>`, A synthesizes, `AWAITING_USER`) — early exit never lands the terminal step on B. Note any skip in the synthesis.

## Measurement & equivalence techniques (hard-won)

These are the traps that turn a "win" into wasted effort or a production bug. Apply them in R1/R3 (A) and enforce them in R2/R4 (B).

**Profile with a SAMPLING profiler, not `cProfile`, to pick the target.** `cProfile` adds fixed per-call instrumentation, so a function called 10^8× looks dominant even when its body is cheap — "optimize" it and the wall-clock won't move. Use `pyinstrument` (in-process, no sudo) or `py-spy` for true wall-clock attribution; cross-check before believing a hotspot. For a hot leaf, the lever is reducing **call count**, not shaving the body. (Real case: a per-cell helper showed 53s in cProfile; tuning its body was wall-clock-neutral — the real cost was its call count, and the actual wins were elsewhere.) Exact profiler commands for Python targets are in [reference/python-toolbox.md](reference/python-toolbox.md).

**"Cheaper" is a measurable axis too, not just wall-clock.** The contract keeps wins that are faster *or cheaper* — for Python, cheaper usually means memory/allocations. Make it a number: peak via `tracemalloc.get_traced_memory()[1]` or `/usr/bin/time -l`/`-v`, allocation deltas via two `tracemalloc` snapshots (commands in the toolbox). A memory-only win (e.g. a generator that streams instead of materializing) still owes the *identical-output* half of the contract — same values, same order.

**Trust back-to-back old-vs-new ratios, not absolute timings.** Shared infra (RDS, CI runners) varies run-to-run under load — the same query measured 124s once and 9s in isolation. Before "fixing" a suspected elephant, re-measure it in isolation; the slowness may be contention, and the fix may be neutral (don't ship it). Always report the candidate's number measured immediately against the baseline on the same input.

**Isolate the candidate when the target is a sub-step of a larger or non-deterministic pipeline.** Don't diff the whole pipeline output — unrelated upstream nondeterminism will swamp the signal. Instead: hook the target function, capture its real input (deep-copy it), then run the **baseline impl vs the candidate impl on that exact same input, in-process**, and compare outputs directly. This isolates the change from upstream noise AND yields a clean old-vs-new timing. For a SQL rewrite, run both query shapes against the **live pipeline engine** (a fresh connection may lack the schema `search_path`).

**Match the equivalence bar to the operation.** Deterministic compute → exact (`assert_frame_equal(check_exact=True, check_dtype=True)`; identical return). SQL aggregates → `SUM`/`AVG` have no guaranteed order, so accept floating-point tolerance (~1e-12), not bit-identity, and say so. **For SQL, plain `EXCEPT` is set-based and silently drops duplicates — it won't catch a candidate that changes row *multiplicity* (exactly the JOIN double-count bug); use `EXCEPT ALL` both directions or `COUNT(*)`+checksum.** Commands and the full equivalence check are in [reference/sql-toolbox.md](reference/sql-toolbox.md). Either way: **a clean diff on sample data is necessary but not sufficient** — also prove the candidate holds on the *invariant* the old code relied on (see B's challenge mandate). When in doubt, construct the adversarial input (duplicate key, NULL, empty) and compare old-vs-new on it directly.

## Surfacing rounds in chat

After every round (yours OR the peer's), print a 5-15 line digest in chat *before* your next action. Use `optimize_digest <N>` from [reference/handoff.sh](reference/handoff.sh) — it extracts agreements + candidate/challenge titles + per-candidate results + net result, truncated.

```
**B's R2 (challenge):**
- ✓ Baseline harness is fair (cold cache, 10M-row sample)
- ! C1: index won't help — the scan isn't the bottleneck, the hash join is
- ! C2: correctness risk — the rewrite drops NULL group
```

The user can interrupt at any moment. Treat any user message as a steer — address it before continuing.

## Shared state in `.optimize/`

Create `.optimize/` at the repo root on init and append `.optimize/` to `.gitignore`. Files:

| File | Purpose | Written by |
|---|---|---|
| `TARGET.md` | What to optimize + the measurement setup (data, harness, metric) + constraints | Active agent on init |
| `STATE.md` | `ROUND`, `ROUNDS`, `STATUS`, `A`, `B`, `EFFORT`, round log | Every round |
| `R1.md` … `R<ROUNDS>.md` | Round content (numbers live here; code lives in the repo) | Actor of that round |
| `bench/` | Benchmark scripts + raw timing output **and the equivalence-check harness**, so both agents run the *same* harness — A commits the equality check here (not just timing) so B can re-run it headless in R4 | Whoever builds the harness (R1) |
| `USER_NOTES.md` | User-injected steers (created lazily) | `optimize_inject` |
| `session.log` + `round-<N>-<peer>.log` | Peer stdout | `optimize_handoff` |

`A` and `B` are fixed for the session — whoever measured in R1 is A. Full templates in [reference/file-formats.md](reference/file-formats.md).

## Entry modes

Both modes accept the [Flags](#flags) (`--number n`, `--model high|xhigh`). Parse them off the invocation first, then write the resolved `ROUNDS:`/`EFFORT:` into `STATE.md` at init.

### Mode 1 — fresh target: `/pair-optimize "<target>" [--number n] [--model high|xhigh]`
You are the orchestrator (A). Write `TARGET.md` (the thing to optimize **and** how it'll be measured — data, harness, metric) and `STATE.md` (`ROUND: 1`, `ROUNDS: <n>`, `STATUS: ACTIVE: <you>`, `A: <you>`, `B: <peer>`, `EFFORT: <effort>`), then do R1. After R1, `ROUND: 2`, `STATUS: WAITING: <peer>`, then `optimize_handoff <peer>` + `optimize_wait`, and stay alive for the rest of A's rounds.

### Mode 2 — continue from session: `/pair-optimize --from-session [--number n] [--model high|xhigh]`
Use when you've just profiled/proposed an optimization mid-conversation and want the peer to challenge it. You are implicitly A; your most-recent baseline+proposal becomes R1. Write `TARGET.md` (enough that B can act cold — B sees only `.optimize/`), write `R1.md`, set `STATE.md` (`ROUND: 2`, `ROUNDS: <n>`, `STATUS: WAITING: <peer>`, …), then `optimize_handoff` + `optimize_wait`.

**Auto-detect Mode 2:** no target arg AND no existing `.optimize/` AND the recent conversation has a baseline+proposal you authored → default to Mode 2. Otherwise prompt for a target. If `.optimize/` already exists, treat as resume — don't overwrite.

### Flags

| Flag | Meaning | Default |
|---|---|---|
| `--number n` (aliases `--rounds n`, `--round n`) | Requested **round cap / depth**, written to `ROUNDS:` (a max — early termination can end sooner). **Normalized to odd and `>= 3`**: even `n` snaps **up** to `n+1`, `n < 3` rises to `3`. Always print a one-line reason before the loop, e.g. `--number 4 can't end on A; using a 5-round cap so A synthesizes last.` | `5` |
| `--model high\|xhigh` | Peer reasoning effort, written to `EFFORT:`. `optimize_handoff` injects `codex exec -c model_reasoning_effort=<v>` / `claude --effort <v>`. Only `high`/`xhigh` accepted; an invalid value should abort before writing `.optimize/`. Omitted → empty `EFFORT:`, each CLI's own default. | unset |

## Handoff

**`optimize_handoff` + `optimize_wait` are orchestrator-only.** Run them only after *your own* non-final A round — never as a cold-woken peer. After writing your round and updating `STATE.md`:

```bash
source ~/.claude/skills/pair-optimize/reference/handoff.sh   # or ~/.agents/...
optimize_handoff codex                                        # or: optimize_handoff claude
```

`optimize_handoff` does the headless invocation correctly (nohup + detach, `--` terminator for claude, `stdbuf` for live logging, injecting the `EFFORT:` flag). Do not call it at the final round — it refuses and tells you to set `STATUS: AWAITING_USER`.

### Then wait — the handoff isn't tracked by the harness

`optimize_handoff` uses `nohup ... &`, which takes the peer **outside the Claude Code harness's process tracking** — you won't be notified when its round lands. Immediately after `optimize_handoff`, call `optimize_wait` so the harness has a tracked process:

```
# Claude Code:
Bash(command="source ~/.claude/skills/pair-optimize/reference/handoff.sh && optimize_wait", run_in_background=true)
# Codex CLI / inline: call optimize_wait in the foreground — it blocks until the peer flips STATE.md.
```

`optimize_wait` polls `.optimize/STATE.md` every 5s and exits when STATUS flips off `WAITING: <peer>`. Exit 0 = your turn; exit 2 = timeout (re-invoke); exit 3 = peer likely crashed (`optimize_status` / `optimize_peer_status <peer>`).

## Hazards

The CLI hazards are pre-solved by `optimize_handoff` — listed so you don't reinvent them. The last two are process rules the contract enforces, not script guards.

| Hazard | Rule |
|---|---|
| `claude -p "<prompt>" <flags>` — flags after prompt hang the CLI | Flags first; use `optimize_handoff`. |
| `claude --add-dir <dir> "<prompt>"` — variadic flag eats prompt | `--` terminator before the prompt. |
| `killall claude` / `pkill codex` to recover | Kills the user's main session. Use `optimize_peer_status <peer>`. |
| `claude -p --bare` — fails auth unless `ANTHROPIC_API_KEY` is set | Don't use `--bare`. |
| Benchmarking with a warm cache / one iteration | Fake wins. State cache state; run enough reps; report spread. |
| Keeping a candidate without an output-equality check | Correctness regression masquerading as a speedup. The contract forbids it. |

## Steering as a human

| Command | What it does |
|---|---|
| `optimize_watch` | `tail -F .optimize/session.log` across all rounds. |
| `optimize_status` | One-screen summary: `STATE.md` + open notes + last 20 log lines. |
| `optimize_inject "<note>"` | Append a USER_NOTE; next agent must address it before their round. |
| `optimize_takeover` | Kill peer by PID, set `STATUS: BLOCKED: human-takeover`. |
| `optimize_resume <peer>` | After takeover + manual edits, hand back. Does NOT bump `ROUND`. |
| `optimize_digest <N>` | Print the terse digest of `R<N>.md`. |

## Common mistakes

| Mistake | Fix |
|---|---|
| Optimizing before measuring | R1 establishes the baseline first. No baseline = no contract. |
| Optimizing something that isn't the bottleneck | Profile in R1; B challenges the bottleneck claim in R2. |
| Trusting `cProfile` to pick the target | It over-weights call-heavy leaves; body tweaks come out neutral. Use a sampling profiler ([techniques](#measurement--equivalence-techniques-hard-won)). |
| "Fixing" an elephant that was really contention | Re-measure in isolation first; same query was 124s under load, 9s isolated. |
| Diffing a whole pipeline that's run-to-run non-deterministic | Isolate: capture the function's input, run old vs new on the SAME input. |
| Treating "identical on sample data" as behaviour-preserving | It isn't. Prove the invariant holds too; construct the adversarial input (dup key, NULL, empty). A unique-key dev sample hid a JOIN double-count bug; EXISTS preserved the union semantics. |
| Claiming a speedup with no number / one noisy run | Report median + spread over N reps; B audits this in R4. |
| Keeping a neutral micro-opt "because it's cleaner" | The contract keeps only *measured* wins. Neutral = revert. |
| Keeping a faster-but-wrong version | Output-equality is half the contract. Wrong = reverted. |
| Peer (B) calling `optimize_handoff`/`optimize_wait` after a B round | Spawns a duplicate orchestrator that races the live one. The peer is one-shot: flip `STATUS: WAITING: <A's CLI name>` and **exit**. |
| Writing `STATUS: WAITING: A` (the role letter) | STATUS names the CLI: `WAITING: claude` / `WAITING: codex` — `optimize_handoff` matches on the name. Read it off STATE.md's `A:` line. |
| Invoking peer at the final round | The final round (`ROUND == ROUNDS`) ends the loop. Surface to the user. |
| Running pair-optimize alongside `.consult/` or `.pair/` in one repo | One pair session per repo. If another exists, abort `STATUS: BLOCKED: collision`. |
| Idling after `optimize_handoff` ("harness will notify me") | It won't — the peer is `nohup`'d. Always follow with `optimize_wait` (background in Claude Code). |

## Resuming

`/pair-optimize` with no args + existing `.optimize/` → resume:
- `WAITING: <you>` → do your round.
- `WAITING: <peer>` → mid-flight; `optimize_watch` or report state.
- `AWAITING_USER` → show the final round file (`R<ROUNDS>.md`) and ask what they want.
- `BLOCKED` → tell the user what's blocked; offer `optimize_resume <peer>`.
Files in this package (7)
  • SKILL.md 24 KB
  • evals/evals.json 2 KB
  • evals/handoff-parsing.sh 3 KB
  • reference/file-formats.md 7 KB
  • reference/handoff.sh 18 KB
  • reference/python-toolbox.md 9 KB
  • reference/sql-toolbox.md 10 KB

Versions

The database has no other skills named pair-optimize.

Database snapshot: 13.11.2026 · package version 12b973086912 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90pair-ratchet
    Use when the user wants to optimize a whole hot path, module, or pipeline — not one isolated query — keeping every measured win and moving to the next bottleneck until none yields a measured win. Loops pair-optimize sessions back-to-back; each session's kept win becomes the next…
  • 100sql-optimization
    Makes a specific slow query fast from planner evidence: Postgres EXPLAIN ANALYZE or Mongo explain(\"executionStats\"), COLLSCAN, N+1, index fit, rewrite, before/after numbers. Use when a query, endpoint or report is slow or DB CPU is high.
  • 100run-cq
    Build, run, test, and smoke-drive cq — the SQL-over-Claude-Code-transcripts CLI (Rust + DuckDB). Use when asked to build cq, run it, try a subcommand, verify a change works end-to-end, or run its tests.
  • 100optimize
    Use when one named path or performance symptom needs a single measured fix. Not for read-only hot-path hypotheses: use fastopt. Not for a full measured-floor campaign: use optimize-extremely.
  • 95duckdb
    DuckDB as a database engine: internals, SQL dialect, storage/indexing, extension system, the Quack remote/client-server protocol, and query optimization/tuning. Use for \"DuckDB\", \"duckdb CLI\", \"embedded OLAP\", \"DuckDB extension\", \"httpfs\", \"spatial\", \"duckdb_fdw\",…
  • 100ask-codex
    Delegate a code analysis, refactoring, or automated-editing task to the OpenAI Codex CLI (codex exec / codex resume), then critically evaluate its output as a peer AI. Use when the user asks to run Codex, references OpenAI Codex, or wants a second model's take on the code.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.