agentleFS
Sign inStart free
ccomkhjccomkhj/skills/pair-ratchet/SKILL.md

pair-ratchet

Skill10 starsChanged 19 days agoMITView on GitHub

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 each session to pair-optimize and never restates its contract; not itself a cold-woken peer.

The file

We split this skill into the rules it gives an agent

6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    The ratchet: every kept optimization is a measured, output-identical win (pair-optimize's contract guarantees no regression), so each kept …

    line 17
  2. Very specific:

    Termination — loop-until-dry: Don't invent a gate; reuse the contract (*no win kept unless measured better*).

    line 35
  3. Very specific:

    If .ratchet/ already exists → this is a resume, not a fresh run (see Resuming).

    line 47
  4. Very specific:

    Write .ratchet/STATE.md: SCOPE, SESSION: 1, MAX_SESSIONS: <m>, UNTIL_DRY: <k>, DRY_COUNT: 0, the passthrough flags (NUMBER, MODEL), and an …

    line 51
  5. Very specific:

    Pick target #1: If the scope is a single runnable, that's the target.

    line 54
  6. Very specific:

    Clean slate: Ensure no .optimize/ is present (archived at the end of the prior iteration).

    line 61

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

pair-ratchet

What this is

The outer loop over pair-optimize. 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<n> rounds, its Claude↔Codex peer, its .optimize/ state. All of that is defined in pair-optimize 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 "<scope>" [flags]

  1. If .ratchet/ already exists → this is a resume, not a fresh run (see 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: <m>, UNTIL_DRY: <k>, 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<ROUNDS>.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/<SESSION>/, 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.
    • 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/<N>/:

  • 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

HazardRule
Two pair sessions in one repo at oncepair-optimize aborts on .optimize/ collision. Run sessions strictly sequentially — archive + clear .optimize/ between iterations. Never concurrent.
The per-session AWAITING_USER promptThe loop suppresses it: read R<ROUNDS>.md instead of asking. The user is checkpointed once, at the end.
Touching pair-optimize's peer mechanicsoptimize_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 targetAdvance 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).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free