Arguments. [<goal-slug>]. e.g. /performance:climb site-build-template-parses
Purpose
Answers "which of these changes actually moved the number, and how far can it go?"
Measure one change at a time: hypothesis, change, commit, measure both arms, apply the rule, keep
or revert, log, until the goal is met. Keep every judgment out of reach of the attempt being
judged: the rule is written first, the harness is frozen, and the baseline is re-measured beside
each attempt.
Read ${CLAUDE_PLUGIN_ROOT}/reference/harness-integrity.md
before the first attempt.
Inputs, or stop
- A goal from
/performance:goal with its floor, its Realistic target and min_attempts. A
goal without min_attempts goes back to /performance:goal; never pick one here, since goal is
human-gated.
- A harness
/performance:snapshot froze: the command, the commit it was frozen at, and its
discrimination result. Send the run back to /performance:snapshot baseline when no harness is
frozen, or when its output carries neither tally. Each harness run must print three numbers: the
goal's counter, a tally of failures and a tally of finished work units.
- A clean checkout.
git status --porcelain in your checkout prints nothing. Refuse
otherwise and name the files: the loop starts from a commit, and uncommitted work is not in it.
- Optional: a holdout harness
/performance:snapshot froze, a second command that prints the
same three numbers on inputs the main harness does not use. It needs its own Frozen: line in
the baseline report with discriminate: exit 0, worded like item 2; send the run back to
/performance:snapshot baseline when the line is missing. Absent means off: the run behaves
exactly as it does without this item, and nothing below that mentions the holdout applies.
Set up, before the first attempt
Memory slice. Use <memory_dir>/<topic-slug>/climb/<goal-slug>/ in your checkout (default
<memory_dir> is .work/), by absolute path: the loop runs in another worktree, and the log
must outlive it. Done when the directory exists.
Keep rule. Write keep-rule.json there with exactly three keys: counter (the goal's
counter, by name), direction (lower or higher) and gain_floor (the change in the counter
that counts as a gain; the host's measured noise for a duration, 0 for a deterministic count).
Show it to the person when one is present. Never edit it during the run: once an attempt
has a number, any change to the file would tailor the rule to that number.
Two worktrees, outside your checkout or in a directory its .gitignore ignores. Start both
at your checkout's HEAD:
- climb's own:
git worktree add -b climb/<goal-slug> <climb-path> <start-sha>. A branch with
that name already exists: stop and ask, since it may hold an earlier run.
- the baseline arm:
git worktree add --detach <baseline-path> <start-sha>. It always sits at
the last kept commit.
Every attempt happens in <climb-path>. Nothing in this skill edits, commits in or resets your
checkout.
Starting measurement. Run the harness once in each worktree. The counters agree, the error
counts are zero and the work counts match, or the harness is not stable enough to climb on:
stop and say which number differed.
Holdout, only when item 4 is given. Write holdout.json in the slice, holding the
holdout's Frozen: command and sha; like keep-rule.json it is never edited during the run.
It is not a key of keep-rule.json, which decide accepts only with its three keys. Then run
the holdout once in each worktree, by absolute path, as step 4 does: the counters agree, the error counts are zero
and the work counts match, or stop and say which number differed. This is a stability check
only; its number is never compared at the end. Run the holdout nowhere else until the run ends.
One attempt
- Read the log:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/climb/scripts/climb_log.py" show --log <slice>/log.tsv.
Do not retry a mechanism already reverted unless the new attempt says what differs.
- State one hypothesis that names a mechanism: what the code does now, why that costs the
counter, and what the change removes. "Templates are parsed once per page; parsing once per
build removes N-1 parses" qualifies. "The renderer does too much" does not: it names no code
path and predicts no number.
- Make one change in
<climb-path> that tests that hypothesis and nothing else. Never edit
the harness files, the holdout harness included. Never read holdout output while forming a
hypothesis; holdout numbers never go into log.tsv, so show carries none.
- Commit it on
climb/<goal-slug>, staging the changed files by name.
- Run the project's tests in
<climb-path>. Record pass or fail.
- Measure both arms in one sitting. Run the snapshot harness
ab.sh with --a running the
harness in <baseline-path> and --b running it in <climb-path>, at the goal's iterations and
percentiles. ab.sh discards each arm's output, so also run the harness once in each worktree
and read its counter, error count and work count. Never compare against a number stored from an
earlier attempt; the baseline arm is re-measured every time. Never run the holdout harness here.
- Decide:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/climb/scripts/climb_log.py" decide --rule <slice>/keep-rule.json --before <baseline counter> --after <attempt counter>.
Settle the verdict in this order, stopping at the first line that applies:
- Tests failed, the error count rose, or the work count differs from the baseline's:
reverted, whatever decide prints. Finishing fewer work units is not a speedup.
decide prints kept: kept.
decide prints reverted, the counter is no worse than the baseline's, and
git diff --numstat <last kept sha> <attempt-sha> shows lines removed and none added:
kept, noted simplification. Deleting code without losing ground on the counter is a
result in its own right.
- Otherwise:
reverted.
- Keep or revert.
- Kept: move the baseline arm to the attempt,
git -C <baseline-path> checkout --detach <attempt-sha>.
- Reverted: in
<climb-path>, git reset --keep <last kept sha>, which moves only climb's own
branch. If it refuses, stop and report the files; never use another reset form to force it.
- Log the row:
python3 "${CLAUDE_PLUGIN_ROOT}/skills/climb/scripts/climb_log.py" append --log <slice>/log.tsv.
Every row passes all nine flags. The outcome goes in --verdict (kept or reverted) and
--tests (pass or fail); the measured numbers in --before, --after and --delta; the
text in --id, --hypothesis, --change and --note. When the verdict is reverted, put the
dropped SHA in --note; git show on that SHA still displays the attempt.
- Pointer: for what
--keep refuses and what it moves, see
git-reset --keep.
As of: 2026-11-10. Recheck trigger: the git-reset page changes the --keep description.
When the run ends
| Logged attempts |
Last kept value |
Budget |
Untried mechanism |
Action |
| any |
any |
spent |
any |
finish; report the target as not met when it is short |
at or above min_attempts |
meets the Realistic target |
left or not set |
any |
finish |
| any |
short of the target, or min_attempts not reached |
left or not set |
at least one |
next attempt |
| any |
short of the target, or min_attempts not reached |
left or not set |
none |
finish; report Next idea: none left and which condition was not reached |
A budget is optional. Without one, the last row is what ends a run that never reaches its target.
min_attempts is a floor on evidence: the attempts after the first kept one show whether the
counter has more room. The goal, the keep rule and the budget stay as written until the run ends.
Choosing the next hypothesis
Smaller first. Between two hypotheses expected to move the counter by about the same amount,
attempt the one with the smaller change first; the number never justifies extra code on its own.
From the log. Group the logged rows by the mechanism each one named. Prefer a mechanism no
row has tried yet over a variant of a reverted one.
After three reverts in a row, run /performance:target against <climb-path> when it is
among the available skills, and take the next hypothesis from its ranking; without it, profile
the harness run once and pick the largest cost no row has touched.
Report what each gain cost. Each kept line in the report carries its git diff --stat
totals, so the reviewer can weigh a small gain against a large change.
Unattended runs
The skill starts no /goal and sets no loop. For a run nobody watches, draft its stop condition
first with /planning:draft-goal-condition when that skill is among the available skills,
naming the goal's target, min_attempts and the budget; without it, write the condition from
those same three items. The person starts the run with that condition.
Finish
- Holdout, only when item 4 is given. Both worktrees sit at the last kept sha. When it equals
the start sha, skip the measurement and report
Holdout: not run (nothing kept). Otherwise
run git -C <baseline-path> checkout --detach <start-sha>, then run the holdout once in each
worktree, by absolute path, and read its counter, error count and work count; no ab.sh run
is needed. Call decide --rule <slice>/keep-rule.json --before <holdout counter on the start sha> --after <holdout counter on the last kept sha>: kept reports held, reverted reports
did not hold. As in step 7.1, a rose error count or a differing work count reports
did not hold whatever decide prints. A run whose kept attempts are all simplifications
(step 7.3) reports whatever decide prints; a did not hold there says only that the holdout
showed no gain. The holdout informs and never reverts: a gain that did not hold is still the
climb's result. Do this before step 1 removes the worktrees.
- Remove both worktrees with
git worktree remove <path>. The branch climb/<goal-slug> stays
and holds the kept commits in commit order. When git worktree remove refuses, leave that
worktree in place, name its path and the files git status --porcelain lists in the report, and
let the person clean it. Never pass --force.
- Report:
Branch: climb/<goal-slug>
Log: <absolute path to log.tsv>
Counter: <counter>, <direction>; Realistic target <Realistic target>
Moved: <start value> -> <last kept value> (<percent change>)
Evidence: min_attempts <n>; logged <n>: kept <k>, reverted <r>
Holdout: <held|did not hold>; <holdout counter on start sha> -> <holdout counter on last kept sha>, or "not run (nothing kept)" (only when a holdout was given; with errors or work counts that differ, name them)
Next idea: <the untried hypothesis most likely to move the counter, or "none left">
Changes, oldest first, one line each:
<sha> <change> (<files> files, +<added> -<removed>)
- Pointer: for which worktrees
remove accepts, see
git-worktree remove.
As of: 2026-10-04 (ignored-only output was also checked by hand: removal succeeds). Recheck
trigger: that section changes what counts as a clean worktree.
Boundary
Does not set the goal or the rule's counter. /performance:goal does, with a person.
Does not freeze the harness. /performance:snapshot does.
Does not decide the result is real. /performance:verify re-derives it in a fresh context.
Does not climb an eval score. For an LLM app scored against an eval set, the person types
/claude-api hillclimb; this skill never starts it.
Pointer: for the /claude-api subcommands, see
https://code.claude.com/docs/en/skills#work-on-claude-api-projects. As of: 2026-10-04.
Recheck trigger: that section drops or renames hillclimb.
Next
/performance:verify on the branch climb/<goal-slug>, with the log path.
Gotchas
- The rule file judges every gain. If an attempt looks good and
decide says reverted, the
attempt is reverted unless it is a pure deletion (step 7, line 3). Change the goal through
/performance:goal before the next run, never during this one.
- A counter that stops moving can mean the harness stopped running the code. Check the work
count before concluding a mechanism had no effect.
- The baseline worktree is detached on purpose. It follows kept commits only; a branch there
would collide with
climb/<goal-slug>.
- Run the harness, and the holdout harness, by absolute path in both worktrees. A relative
path run from the wrong directory measures the same tree twice.
1---2name: climb3description: "Keep-or-revert loop on a frozen harness: one hypothesis and one commit per attempt, both arms re-measured every time, kept by a rule written before the first attempt, logged outside the tree, in its own worktree and branch. Use when: 'keep trying changes until this counter drops', 'hill-climb this benchmark', 'iterate on this until the target is met', 'run an optimization loop'. After /performance:snapshot baseline, before /performance:verify. Skip when: the score comes from an eval set for an LLM app (`/claude-api hillclimb`); one before-and-after comparison (`/performance:snapshot`)."4user-invocable: true5argument-hint: "[<goal-slug>]"6disable-model-invocation: false7metadata:8 source: https://skillmd.com/skills/melodic-software/climb9 workflow-stage: implement10 summary: Keep or revert one measured change at a time until the goal is met11---1213**Arguments.** `[<goal-slug>]`. e.g. /performance:climb site-build-template-parses1415## Purpose1617Answers **"which of these changes actually moved the number, and how far can it go?"**1819Measure one change at a time: hypothesis, change, commit, measure both arms, apply the rule, keep20or revert, log, until the goal is met. Keep every judgment out of reach of the attempt being21judged: the rule is written first, the harness is frozen, and the baseline is re-measured beside22each attempt.2324Read [`${CLAUDE_PLUGIN_ROOT}/reference/harness-integrity.md`](${CLAUDE_PLUGIN_ROOT}/reference/harness-integrity.md)25before the first attempt.2627## Inputs, or stop28291. **A goal from `/performance:goal`** with its floor, its Realistic target and `min_attempts`. A30 goal without `min_attempts` goes back to `/performance:goal`; never pick one here, since goal is31 human-gated.322. **A harness `/performance:snapshot` froze**: the command, the commit it was frozen at, and its33 discrimination result. Send the run back to `/performance:snapshot baseline` when no harness is34 frozen, or when its output carries neither tally. Each harness run must print three numbers: the35 goal's counter, a tally of failures and a tally of finished work units.363. **A clean checkout.** `git status --porcelain` in your checkout prints nothing. Refuse37 otherwise and name the files: the loop starts from a commit, and uncommitted work is not in it.384. **Optional: a holdout harness `/performance:snapshot` froze**, a second command that prints the39 same three numbers on inputs the main harness does not use. It needs its own `Frozen:` line in40 the baseline report with `discriminate: exit 0`, worded like item 2; send the run back to41 `/performance:snapshot baseline` when the line is missing. **Absent means off**: the run behaves42 exactly as it does without this item, and nothing below that mentions the holdout applies.4344## Set up, before the first attempt45461. **Memory slice.** Use `<memory_dir>/<topic-slug>/climb/<goal-slug>/` in your checkout (default47 `<memory_dir>` is `.work/`), by absolute path: the loop runs in another worktree, and the log48 must outlive it. Done when the directory exists.492. **Keep rule.** Write `keep-rule.json` there with exactly three keys: `counter` (the goal's50 counter, by name), `direction` (`lower` or `higher`) and `gain_floor` (the change in the counter51 that counts as a gain; the host's measured noise for a duration, `0` for a deterministic count).52 Show it to the person when one is present. **Never edit it during the run**: once an attempt53 has a number, any change to the file would tailor the rule to that number.543. **Two worktrees, outside your checkout or in a directory its `.gitignore` ignores.** Start both55 at your checkout's `HEAD`:56 - climb's own: `git worktree add -b climb/<goal-slug> <climb-path> <start-sha>`. A branch with57 that name already exists: stop and ask, since it may hold an earlier run.58 - the baseline arm: `git worktree add --detach <baseline-path> <start-sha>`. It always sits at59 the last kept commit.6061 Every attempt happens in `<climb-path>`. Nothing in this skill edits, commits in or resets your62 checkout.634. **Starting measurement.** Run the harness once in each worktree. The counters agree, the error64 counts are zero and the work counts match, or the harness is not stable enough to climb on:65 stop and say which number differed.665. **Holdout, only when item 4 is given.** Write `holdout.json` in the slice, holding the67 holdout's `Frozen:` command and sha; like `keep-rule.json` it is never edited during the run.68 It is not a key of `keep-rule.json`, which `decide` accepts only with its three keys. Then run69 the holdout once in each worktree, by absolute path, as step 4 does: the counters agree, the error counts are zero70 and the work counts match, or stop and say which number differed. This is a stability check71 only; its number is never compared at the end. Run the holdout nowhere else until the run ends.7273## One attempt74751. **Read the log**: `python3 "${CLAUDE_PLUGIN_ROOT}/skills/climb/scripts/climb_log.py" show --log <slice>/log.tsv`.76 Do not retry a mechanism already reverted unless the new attempt says what differs.772. **State one hypothesis that names a mechanism**: what the code does now, why that costs the78 counter, and what the change removes. "Templates are parsed once per page; parsing once per79 build removes N-1 parses" qualifies. "The renderer does too much" does not: it names no code80 path and predicts no number.813. **Make one change** in `<climb-path>` that tests that hypothesis and nothing else. Never edit82 the harness files, the holdout harness included. Never read holdout output while forming a83 hypothesis; holdout numbers never go into `log.tsv`, so `show` carries none.844. **Commit it** on `climb/<goal-slug>`, staging the changed files by name.855. **Run the project's tests** in `<climb-path>`. Record `pass` or `fail`.866. **Measure both arms in one sitting.** Run the snapshot harness `ab.sh` with `--a` running the87 harness in `<baseline-path>` and `--b` running it in `<climb-path>`, at the goal's iterations and88 percentiles. `ab.sh` discards each arm's output, so also run the harness once in each worktree89 and read its counter, error count and work count. Never compare against a number stored from an90 earlier attempt; the baseline arm is re-measured every time. Never run the holdout harness here.917. **Decide**: `python3 "${CLAUDE_PLUGIN_ROOT}/skills/climb/scripts/climb_log.py" decide --rule <slice>/keep-rule.json --before <baseline counter> --after <attempt counter>`.92 Settle the verdict in this order, stopping at the first line that applies:93 1. Tests failed, the error count rose, or the work count differs from the baseline's:94 `reverted`, whatever `decide` prints. Finishing fewer work units is not a speedup.95 2. `decide` prints `kept`: `kept`.96 3. `decide` prints `reverted`, the counter is no worse than the baseline's, and97 `git diff --numstat <last kept sha> <attempt-sha>` shows lines removed and none added:98 `kept`, noted `simplification`. Deleting code without losing ground on the counter is a99 result in its own right.100 4. Otherwise: `reverted`.1018. **Keep or revert.**102 - Kept: move the baseline arm to the attempt, `git -C <baseline-path> checkout --detach <attempt-sha>`.103 - Reverted: in `<climb-path>`, `git reset --keep <last kept sha>`, which moves only climb's own104 branch. If it refuses, stop and report the files; never use another reset form to force it.1059. **Log the row**: `python3 "${CLAUDE_PLUGIN_ROOT}/skills/climb/scripts/climb_log.py" append --log <slice>/log.tsv`.106 Every row passes all nine flags. The outcome goes in `--verdict` (`kept` or `reverted`) and107 `--tests` (`pass` or `fail`); the measured numbers in `--before`, `--after` and `--delta`; the108 text in `--id`, `--hypothesis`, `--change` and `--note`. When the verdict is `reverted`, put the109 dropped SHA in `--note`; `git show` on that SHA still displays the attempt.110111- **Pointer**: for what `--keep` refuses and what it moves, see112 [git-reset `--keep`](https://git-scm.com/docs/git-reset#Documentation/git-reset.txt---keep).113 **As of**: 2026-11-10. **Recheck trigger**: the git-reset page changes the `--keep` description.114115## When the run ends116117| Logged attempts | Last kept value | Budget | Untried mechanism | Action |118|---|---|---|---|---|119| any | any | spent | any | finish; report the target as not met when it is short |120| at or above `min_attempts` | meets the Realistic target | left or not set | any | finish |121| any | short of the target, or `min_attempts` not reached | left or not set | at least one | next attempt |122| any | short of the target, or `min_attempts` not reached | left or not set | none | finish; report `Next idea: none left` and which condition was not reached |123124A budget is optional. Without one, the last row is what ends a run that never reaches its target.125126`min_attempts` is a floor on evidence: the attempts after the first kept one show whether the127counter has more room. The goal, the keep rule and the budget stay as written until the run ends.128129## Choosing the next hypothesis130131- **Smaller first.** Between two hypotheses expected to move the counter by about the same amount,132 attempt the one with the smaller change first; the number never justifies extra code on its own.133134- **From the log.** Group the logged rows by the mechanism each one named. Prefer a mechanism no135 row has tried yet over a variant of a reverted one.136- **After three reverts in a row**, run `/performance:target` against `<climb-path>` when it is137 among the available skills, and take the next hypothesis from its ranking; without it, profile138 the harness run once and pick the largest cost no row has touched.139- **Report what each gain cost.** Each kept line in the report carries its `git diff --stat`140 totals, so the reviewer can weigh a small gain against a large change.141142## Unattended runs143144The skill starts no `/goal` and sets no loop. For a run nobody watches, draft its stop condition145first with `/planning:draft-goal-condition` when that skill is among the available skills,146naming the goal's target, `min_attempts` and the budget; without it, write the condition from147those same three items. The person starts the run with that condition.148149## Finish1501510. **Holdout, only when item 4 is given.** Both worktrees sit at the last kept sha. When it equals152 the start sha, skip the measurement and report `Holdout: not run (nothing kept)`. Otherwise153 run `git -C <baseline-path> checkout --detach <start-sha>`, then run the holdout once in each154 worktree, by absolute path, and read its counter, error count and work count; no `ab.sh` run155 is needed. Call `decide --rule <slice>/keep-rule.json --before <holdout counter on the start sha>156 --after <holdout counter on the last kept sha>`: `kept` reports `held`, `reverted` reports157 `did not hold`. As in step 7.1, a rose error count or a differing work count reports158 `did not hold` whatever `decide` prints. A run whose kept attempts are all simplifications159 (step 7.3) reports whatever `decide` prints; a `did not hold` there says only that the holdout160 showed no gain. The holdout informs and never reverts: a gain that did not hold is still the161 climb's result. Do this before step 1 removes the worktrees.1621. Remove both worktrees with `git worktree remove <path>`. The branch `climb/<goal-slug>` stays163 and holds the kept commits in commit order. When `git worktree remove` refuses, leave that164 worktree in place, name its path and the files `git status --porcelain` lists in the report, and165 let the person clean it. Never pass `--force`.1662. Report:167168```text169Branch: climb/<goal-slug>170Log: <absolute path to log.tsv>171Counter: <counter>, <direction>; Realistic target <Realistic target>172Moved: <start value> -> <last kept value> (<percent change>)173Evidence: min_attempts <n>; logged <n>: kept <k>, reverted <r>174Holdout: <held|did not hold>; <holdout counter on start sha> -> <holdout counter on last kept sha>, or "not run (nothing kept)" (only when a holdout was given; with errors or work counts that differ, name them)175Next idea: <the untried hypothesis most likely to move the counter, or "none left">176Changes, oldest first, one line each:177 <sha> <change> (<files> files, +<added> -<removed>)178```179180- **Pointer**: for which worktrees `remove` accepts, see181 [git-worktree `remove`](https://git-scm.com/docs/git-worktree#Documentation/git-worktree.txt-remove).182 **As of**: 2026-10-04 (ignored-only output was also checked by hand: removal succeeds). **Recheck183 trigger**: that section changes what counts as a clean worktree.184185## Boundary186187- **Does not set the goal or the rule's counter.** `/performance:goal` does, with a person.188- **Does not freeze the harness.** `/performance:snapshot` does.189- **Does not decide the result is real.** `/performance:verify` re-derives it in a fresh context.190- **Does not climb an eval score.** For an LLM app scored against an eval set, the person types191 `/claude-api hillclimb`; this skill never starts it.192193- **Pointer**: for the `/claude-api` subcommands, see194 <https://code.claude.com/docs/en/skills#work-on-claude-api-projects>. **As of**: 2026-10-04.195 **Recheck trigger**: that section drops or renames `hillclimb`.196197## Next198199`/performance:verify` on the branch `climb/<goal-slug>`, with the log path.200201## Gotchas202203- **The rule file judges every gain.** If an attempt looks good and `decide` says `reverted`, the204 attempt is reverted unless it is a pure deletion (step 7, line 3). Change the goal through205 `/performance:goal` before the next run, never during this one.206- **A counter that stops moving can mean the harness stopped running the code.** Check the work207 count before concluding a mechanism had no effect.208- **The baseline worktree is detached on purpose.** It follows kept commits only; a branch there209 would collide with `climb/<goal-slug>`.210- **Run the harness, and the holdout harness, by absolute path in both worktrees.** A relative211 path run from the wrong directory measures the same tree twice.