caveman--caveman-optimize

Evaluate Caveman report-only optimization observations with operator-chosen candidates and paired baseline evaluations.

Updated Dec 3, 2025
One-click install
npx skills add https://github.com/hhenrichsen/dots --skill caveman-caveman-optimize-hhenrichsen
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: caveman--caveman-optimize
Source: https://github.com/hhenrichsen/dots/tree/main/dot_skills/caveman/caveman-optimize
Command: npx skills add https://github.com/hhenrichsen/dots --skill caveman-caveman-optimize-hhenrichsen

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Caveman optimization reports describe aggregate usage shapes but do not prove that a code change is safe or worthwhile. This Skill turns a report-only observation into an operator-approved candidate change validated by a paired baseline evaluation, preventing premature edits and unsupported savings claims. ## 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 Workflow: Requires an explicit operator choice before inspecting callsites, and approval of the candidate and eval design before any edit. - Paired Baseline Evaluation: Designs and runs baseline and candidate arms on identical fixed inputs, recording quality checks, token or byte cost measures, fixtures, and confounders. - Use Case: A Caveman report flags a tool-output-size-profile observation. Use this Skill to present the observation to the operator, design a minimal candidate change at the evidenced callsite, run a paired eval, and report keep, reject, or inconclusive without claiming dollar savings. ## Quick Start Ask the AI to inspect the current Caveman optimization report and walk you through evaluating one observation with a paired baseline test.

Frequently Asked Questions about caveman--caveman-optimize

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

FAQPage Schema
How do I evaluate a Caveman optimization report?▼

Run `caveman opportunities list` with a logged-in CLI session and read only the `report_only_observations` array. Present the supported observations to the operator for an explicit choice, then design a candidate change and paired baseline evaluation before editing any code.

What are report-only observations in Caveman?▼

Report-only observations are diagnostic rows describing recorded aggregate shapes, such as context-window or tool-output-size profiles. They have an immutable zero dollar band and no actuation path, so they cannot be ranked by value, marked implemented, or converted into savings claims.

Can this skill apply code changes automatically?▼

No. The workflow requires an explicit operator choice of an observation and approval of the candidate and eval design before any edit. If approval is missing, instrumentation is absent, or the CLI is unavailable, the skill stops without editing and reports the blocker.

What happens if the Caveman CLI is unavailable or authentication fails?▼

The skill stops without editing 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.

Why can't token reductions be reported as dollar savings?▼

Token or byte reductions from a local paired eval only support the stated candidate on the stated fixture. Converting them to dollars requires provider-complete, same-request accounting from the product's verified methods, which report-only profiles do not supply.

Which Caveman profile ids are retired and must not be used?▼

The retired ids are `context-window-bloat`, `tool-catalog-utilization`, and `verbose-tool-output`. Any occurrence in stale proposals or old responses is historical context only and must never be revived for money, recipe, or lifecycle claims.