mcpField
H
hillclimbing

hillclimbing

github.com/bostonaholicAgent workflows246 installsUpdated 1d ago
Repository

About hillclimbing

hillclimbing is a skill for iteratively improving work against a measurable check while preserving guardrails. It is intended for tasks with explicit criteria and requires evidence-based changes, reversible iterations, and a final verification.

Key features

  1. 01Define a scored pass/fail check
  2. 02Record goals, thresholds, and guardrails
  3. 03Make one evidence-based change per iteration
  4. 04Revert changes that do not improve results
  5. 05Preserve the best state and log iterations
  6. 06Stop only at defined completion or blocker states

Use cases

  1. 01Improve a project against a measurable criterion
  2. 02Tune work while keeping existing checks passing
  3. 03Track iterations within a user-stated budget

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/bostonaholic/skills --skill hillclimbing

After installing, type/hillclimbingin Claude Code to confirm it loaded.

Bundled filesagents/openai.yaml

Details

From the project README

Hillclimbing

1. Fix the check before the first change

  • Turn the criteria into a check with a pass or fail result and a score that moves as the work gets closer.
  • Record, verbatim: the goal and criteria as stated, the check and its threshold, guardrails (checks that pass now and must still pass), and the budget, only if the user gave one.

If a criterion cannot be made checkable, ask once, now, and propose a check. This is the only planned question.

Run the check and guardrails for a baseline. If the check already passes, report that and stop. Keep the record and iteration log in a progress file outside the working tree, and reread it after a context reset.

2. Climb

Each iteration:

  • Make one change chosen from the last run's evidence, small enough to trace a score change to it.
  • Rerun the check and guardrails.
  • Keep it only if the score improved and every guardrail passes; otherwise revert it exactly.
  • Log one line: change, score, kept or reverted.
  • Keep the best state recoverable.
  • Never ask whether to continue between iterations.

A noisy score needs several runs per measurement; compare medians.

After three iterations without gain, name the assumption every failed attempt shares and take a larger step that drops it. Never retry a reverted change. A plateau is not a reason to stop.

3. Never move the goalposts

To reach the criteria, never:

  • edit, skip, delete, or loosen a test, assertion, threshold, or the check
  • special-case the check's inputs, such as hardcoded expected outputs
  • suppress what the check reports, such as swallowed errors or bypassed hooks
  • narrow the check to a subset or smaller sample

A wrong check (a test asserts the old bug) is a blocker for the user, not a change to make.

4. Stop only on one of these

  1. Met. Rerun the full check and every guardrail fresh, from the final state. They pass. An earlier pass, a subset, or a partial run does not count.
  2. Budget spent. The user's stated budget, never one invented here.
  3. Blocked on the user. The next step needs a permission, a credential, a destructive or outward-facing action that needs confirmation, a choice between conflicting criteria, or a fix to a wrong check. Or the criteria are provably unreachable: name the constraint and the measurement or source that proves it. "Hard" and "many attempts failed" are not proof. Finish every step that does not depend on the blocker first.

Final report, adapted as needed:

Status: met | budget spent | blocked: <what is needed from the user>
Score: <baseline> -> <final> (threshold <threshold>)
Check: <command>
<its output from the final run>
Iterations: <n> (<kept> kept, <reverted> reverted)

Comments

Markdown supported