hillclimb

Files (2)

• SKILL.md
• opening-a-pr.md · references/

SKILL.md (first lines)

# Hillclimb

**Own the metric and the experiment's integrity. Supervise and review; delegate attempts.** This is for sustained, iterative improvement of one measurable thing. A one-off fix is not a hillclimb. One change, one measurement, keep or revert. Never stack untested changes or claim a win from inspection alone.

1. **Ground.** Read and apply [`how`](../how/SKILL.md) to the target. Name realistic workload dimensions (data size, history, state, concurrency). Select a case that reproduces the user's complaint. If none does, fix the repro first. Choose one metric, its direction, and a stop predicate with a target **and a minimum number of attempts**. Use user-specified numbers; otherwise agree them before the loop.
2. **Freeze a sensitive harness.** Build one repeatable command that emits the metric. First show it separates contrasting realistic workloads, then freeze its workload and measurement method. Sample enough to clear noise (e.g. median of N runs). Record the baseline and a passing regression gate before changing code.
3. **Open the log.** Read and apply [`show-me-your-work`](../show-me-your-work/SKILL.md). Use its canonical `decisions.tsv` format and helper, one row per iteration. Put the attempt id, mechanism/hypothesis and change in `decision`/`why`; point `evidence` at a durable measurement artifact containing before, after, delta and gate result; record kept or reverted in `result`. Keep the log out of the repo by default and read it before each attempt.
4. **Hypothesize.** Each attempt must name a specific mechanism from the grounded architecture, not an unspecific tweak.
5. **Loop, one hypothesis per iteration.** Delegate the scoped change to a Pinnacle `subagent` task with explicit write tools (`read,grep,find,ls,bash,edit,write`). Review the actual diff. Parallel independent hypotheses require separately prepared Jujutsu workspaces or Git worktrees and separate baselines, not multiple writers in one tree. Measure before and after using the frozen harness; run the regression gate. Keep only a result past noise with the gate green. Otherwise revert that attempt in full, preserving unrelated changes. Commit each accepted fix separately with a conventional message, staging only changed files (in Git, `git add <paths>`, never `-A`; in Jujutsu, use a dedicated change and `jj new`). Log each attempt, kept or reverted. Verify one iteration before starting the next.
6. **Push past the first plateau.** After several rejects, pivot category, combine independently measured near-misses, re-read the source, or try a radical alternative. Correctness and simplicity outrank the number. Revert a win that breaks behavior; keep a simplification that holds the number.
7. **Stop honestly.** Stop at the agreed predicate, or when remaining ideas are marginal and not worth their cost. Do not relax the predicate or stop while cheap hypotheses remain. Surface a blocker rather than spinning.
8. **Prepare the PR.** Follow [`references/opening-a-pr.md`](references/opening-a-pr.md) with accepted commits in order. This is hillclimb's own PR path, not `visual-pr`. If pushing or PR creation was not explicitly authorized, prepare the description and ask before remote operations.

**Reply:** metric and target, baseline → final with percent delta, iterations (kept/reverted), accepted fixes, `decisions.tsv` path, and the best remaining hypothesis. Include the measured command and regression gate.

From luckenco/pinnacle, MIT.

More from luckenco/pinnacle