caveman-optimize

Evaluates Caveman report-only observations and tests operator-approved optimization candidates with paired baseline comparisons.

Updated Aug 20, 2026
One-click install
npx skills add https://github.com/bittlinkm/claude-setup --skill caveman-optimize-bittlinkm
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: caveman-optimize
Source: https://github.com/bittlinkm/claude-setup/tree/main/skills/caveman-optimize
Command: npx skills add https://github.com/bittlinkm/claude-setup --skill caveman-optimize-bittlinkm

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Caveman's report-only repository observations describe aggregate usage shapes but do not tell you what to change or whether a change is safe. This Skill turns those observations into an operator-chosen, evidence-first optimization workflow with a paired baseline/candidate evaluation, preventing premature edits, invented savings claims, and unsafe actuation. ## Core Features & Use Cases - Observation Reading: Runs caveman opportunities list and reads only the report_only_observations array, preserving server-provided titles and observations verbatim while rejecting retired profile ids. - Operator-Gated Candidate Design: Requires an explicit operator choice before inspecting callsites, then proposes one minimal candidate change with a paired eval using identical fixed inputs for both arms. - Guarded Application and Reporting: Applies only the approved candidate, runs the paired evaluation plus repository checks, reverts on quality regression or inconclusive results, and reports outcomes without converting token reductions into dollar savings. - Use Case: A Caveman report shows a tool-output-size-profile observation. The operator selects it, the Skill identifies the responsible callsite, proposes a minimal change, runs baseline and candidate on the same fixture, and reports whether the candidate earned adoption. ## Quick Start Ask the assistant to list the current Caveman report-only observations and help evaluate an optimization candidate for one of them.

Frequently Asked Questions about caveman-optimize

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I act on a Caveman report-only observation?

Run `caveman opportunities list` with a logged-in CLI, read only the `report_only_observations` array, and explicitly choose one supported observation. The Skill then inspects candidate callsites, proposes a minimal change with a paired eval, and edits only after your approval.

What is a paired baseline and candidate evaluation?

A paired eval runs the baseline code and the candidate change on identical fixed inputs, recording the same quality check and the same token, byte, or provider-counted cost measure for both arms. If the arms did not use identical inputs and measurement, the comparison is discarded.

Which Caveman observation profiles are supported?

The supported ids are context-window-profile, tool-catalog-profile, tool-output-size-profile, and exploration-load-profile. Retired ids such as context-window-bloat, tool-catalog-utilization, and verbose-tool-output are treated as historical context only and never acted on.

Can this Skill estimate dollar savings from token reductions?

No. Report-only profiles have an immutable zero band, and the Skill never converts token or byte reductions into dollars without provider-complete, same-request accounting from verified product methods. A local paired result supports only the stated candidate on the stated fixture.

What happens if the Caveman CLI is unavailable or not authenticated?

The Skill stops without editing anything and reports the exact blocker. It does not fall back to a raw gateway Cave Plan or a project API key, because those surfaces do not provide the report-only observation contract.

When does the Skill revert an optimization candidate?

The candidate edit is reverted when the quality check regresses or the resource measurement is inconclusive. Only that candidate edit is reverted, and the result is reported as not earning adoption.