# Pair 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 session's baseline (a ratchet that only tightens), stopping when the well is dry or a session cap is hit. Delegates eac…

- **Type:** Skill
- **Install:** `agentstack add skill-ccomkhj-skills-pair-ratchet`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ccomkhj](https://agentstack.voostack.com/s/ccomkhj)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ccomkhj](https://github.com/ccomkhj)
- **Source:** https://github.com/ccomkhj/skills/tree/main/pair-ratchet

## Install

```sh
agentstack add skill-ccomkhj-skills-pair-ratchet
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# pair-ratchet

## What this is

The **outer loop** over [pair-optimize](../pair-optimize/SKILL.md). One `/pair-optimize`
run optimizes one concrete target and stops to ask the user. `pair-ratchet`
runs those sessions **back-to-back across a scope** — profile the scope, optimize
the dominant bottleneck, then the next, then the next — until the **ratchet**
can't move.

**The ratchet:** every kept optimization is a measured, output-identical win
(pair-optimize's contract guarantees no regression), so each kept win becomes
the new immovable **baseline** for the next session. The loop only ever
tightens; it never slips back. "Why did we stop?" has a binary answer: the
ratchet didn't move.

**Single source of truth.** Each session runs the *full* pair-optimize protocol
— its contract, its R1–R rounds, its Claude↔Codex peer, its `.optimize/`
state. All of that is defined in [pair-optimize](../pair-optimize/SKILL.md) and
is **not** restated here. This skill owns only what the single-session skill
lacks: **target selection** and **termination**.

## The two responsibilities the loop adds

- **Target selection** — what gets optimized next. You don't need a new
  profiler: pair-optimize's R1 already identifies the real bottleneck with
  evidence and ranks candidates. The **residual profile after the kept win**
  names the next target. Feed it forward.
- **Termination — loop-until-dry.** Don't invent a gate; reuse the contract
  (*no win kept unless measured better*). Stop after `--until-dry k`
  **consecutive sessions that keep zero wins** (default `k=1`), or when
  `--max-sessions m` is reached (default `5`), whichever comes first.

## The loop

Outer state lives in `.ratchet/` (kept separate from pair-optimize's
`.optimize/` so the two never collide). Append `.ratchet/` to `.gitignore`.

### Init — fresh scope: `/pair-ratchet "" [flags]`

1. If `.ratchet/` already exists → this is a **resume**, not a fresh run (see
   [Resuming](#resuming)). If `.optimize/` exists with no `.ratchet/` → a bare
   pair-optimize session is mid-flight; abort `STATUS: BLOCKED: collision` and
   tell the user to finish or clear it.
2. Write `.ratchet/STATE.md`: `SCOPE`, `SESSION: 1`, `MAX_SESSIONS: `,
   `UNTIL_DRY: `, `DRY_COUNT: 0`, the passthrough flags (`NUMBER`, `MODEL`),
   and an empty ratchet log.
3. **Pick target #1.** If the scope is a single runnable, that's the target. If
   it's a module/pipeline, profile it (sampling profiler — see pair-optimize's
   measurement techniques) to find the dominant runnable bottleneck. Record it
   as `TARGET` in `STATE.md`.

### Each iteration

1. **Clean slate.** Ensure no `.optimize/` is present (archived at the end of the
   prior iteration). If one lingers, finish/clear it first.
2. **Run one pair-optimize session** on the current `TARGET`, Mode 1, passing
   `--number`/`--model` through. Follow pair-optimize exactly — *except* its
   terminal: **you are the user it would stop to ask.** When the session reaches
   synthesis (`R.md`, `STATUS: AWAITING_USER`), do **not** prompt anyone
   — read the synthesis yourself.
3. **Click the ratchet.** From the synthesis, record this session's kept
   candidates + their numbers into `.ratchet/STATE.md`'s ratchet log. The kept
   code is already in the tree, so it is automatically the new baseline. Zero
   kept wins is a valid outcome.
4. **Archive + clear.** Move `.optimize/` → `.ratchet/runs//`, then
   remove `.optimize/` so the next session inits clean.
5. **Update the dry counter.** Zero kept wins this session → `DRY_COUNT += 1`;
   otherwise `DRY_COUNT: 0`.
6. **Terminate or advance.**
   - `DRY_COUNT >= UNTIL_DRY` (well dry) **or** `SESSION >= MAX_SESSIONS` →
     stop; write the [final report](#final-report).
   - Else pick the **next target** from this session's residual profile (the
     next-ranked bottleneck in its `R1.md`, or re-profile the scope now that the
     win landed), bump `SESSION`, set the new `TARGET`, loop.

### Final report

The **only** user-facing checkpoint. Aggregate across every `.ratchet/runs//`:

- Per session: target, kept candidate(s) with baseline→after numbers, or "no
  measured win."
- **Net ratcheted result**: combined improvement vs the original scope baseline.
- Anything still `UNVERIFIED` (a target that couldn't be measured).
- **Why it stopped**: `dry` (k consecutive empty sessions) or `cap`
  (max-sessions). Then `STATUS: DONE` and surface to the user.

## Hazards

| Hazard | Rule |
|---|---|
| Two pair sessions in one repo at once | pair-optimize aborts on `.optimize/` collision. Run sessions **strictly sequentially** — archive + clear `.optimize/` between iterations. Never concurrent. |
| The per-session `AWAITING_USER` prompt | The loop **suppresses** it: read `R.md` instead of asking. The user is checkpointed once, at the end. |
| Touching pair-optimize's peer mechanics | `optimize_handoff`/`optimize_wait` are the *session* orchestrator's job, inside pair-optimize. The ratchet loop never calls them. |
| Looping forever on a noisy target | `--max-sessions` is a hard cap regardless of dry-count. Always set it. |
| A session keeps nothing but you re-pick the same target | Advance the target from the *residual* profile; never re-feed a target a session already exhausted. |

## Resuming

`/pair-ratchet` with no args + existing `.ratchet/` → read `STATE.md`:

- A session is mid-flight (`.optimize/` present) → defer to pair-optimize's own
  resume on `.optimize/`; when it reaches synthesis, continue this loop at
  iteration step 3.
- Between sessions (`STATUS: ACTIVE`, no `.optimize/`) → start the next iteration
  from the recorded `TARGET`.
- `STATUS: DONE` → reprint the final report.
- `STATUS: BLOCKED` → tell the user what's blocked.

## Install

Orchestrator-only — it is never cold-woken as a peer, so it needs a symlink only
into `~/.claude/skills` (the per-iteration Codex peer resumes *pair-optimize*,
not this skill, so no `~/.agents/skills` symlink is required).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ccomkhj](https://github.com/ccomkhj)
- **Source:** [ccomkhj/skills](https://github.com/ccomkhj/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-ccomkhj-skills-pair-ratchet
- Seller: https://agentstack.voostack.com/s/ccomkhj
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.